Connect an assistant

What an assistant can do#

Each tool is a job rather than an endpoint. Instead of listNewsletterInsights with four query parameters, the assistant gets “which readers am I about to lose”, and the steps behind it are run for it. That is the whole design: a model that has to assemble a request from a reference will assemble it wrong occasionally, and occasionally is often enough to matter when the subject is somebody's audience.

The questions it can answer include:

• How did my latest article do, and what did readers say about it?
• Who are my most engaged readers, and who is drifting away?
• What is my community talking about right now?
• Where did my new subscribers come from?
• What have I not sent yet, and why is my custom domain not live?
• Draft this article, send me a test copy, then schedule it for Tuesday.

It can do only what you approved. Access is granted per newsletter and per area (content, audience, sending, insights, settings, webhooks), each at read or write. Every tool says which it needs, the assistant is told what its connection holds, and a tool that needs more is refused with the reason. Tools that change something say so, which is what a client uses to ask you before running one. Sending to your list emails real people and cannot be undone, so the assistant is told to confirm with you first.

One connection covers every newsletter you granted. Each tool takes the newsletter to act on, and the assistant can list them, so “how did my other newsletter do this week” works without reconnecting. If you mostly work on one, make it the default by adding it to the URL:

https://api.usecommune.com/mcp?newsletter=your-handle

Connect a client#

Give the client this URL and nothing else. It will send its first request without a credential, get a 401 that tells it where to go, register itself, and send you to Commune to sign in and approve it. You tick the newsletters it may use, the screen lists what it will be able to do on them, and that is the whole setup. No key, nothing to paste, nothing to keep safe.

https://api.usecommune.com/mcp

In Claude Code, that is one command:

claude mcp add --transport http commune https://api.usecommune.com/mcp

In a client configured by file, it is a server entry with a URL and no headers. The absence of a headers block is the point: a client that finds no credential there starts the browser flow instead.

{
  "mcpServers": {
    "commune": {
      "type": "http",
      "url": "https://api.usecommune.com/mcp"
    }
  }
}

The consent screen always appears, even if you are already signed in to Commune. Being signed in is not the same as agreeing to hand an application your subscribers' email addresses, so it asks, every time a new application connects, and no newsletter is ticked until you tick it. If what the application asked for includes sending, that is the loudest line on the screen.

If your client cannot open a browser#

Some clients can send a header but cannot start an OAuth flow. Those take an API key on the same URL. It is the fallback rather than the advice, and the difference matters: a key is long lived, it reads subscriber email addresses, and unlike a connection it sits in a configuration file until somebody revokes it.

{
  "mcpServers": {
    "commune": {
      "type": "http",
      "url": "https://api.usecommune.com/mcp",
      "headers": { "Authorization": "Bearer cmn_sk_..." }
    }
  }
}

Mint one in Settings, API keys, choosing the newsletters it may reach and what it may do on each. Each tool's description ends with what it needs, so tick those. A key granted nothing on a newsletter authenticates and is refused by every tool, which is a confusing failure to debug: it passes every check you would think to run and is still refused. What bounds a key is that it reaches only the newsletters you chose, may do only what you ticked on each, cannot mint a successor, has every subscriber read recorded against it, and is revocable in one click.

A key that reaches several newsletters works the same way as a connection: tools take the newsletter to act on, and ?newsletter= on the URL sets a default.

When it does not work#

Ask the API rather than the MCP endpoint. This tells you whether the key or the client is at fault, and it answers with a status code rather than with a transport:

curl -sS https://api.usecommune.com/newsletters \
  -H "Authorization: Bearer cmn_sk_..."

• 200 with the key's newsletters in data: the key is live. If the client still fails, the problem is the client or what the key was granted.
• 200 with an empty data: the key reaches no newsletter. It was granted none, or you have since lost your place on the ones it named. The MCP endpoint refuses it.
• 401: the key is missing, revoked or expired. Mint a new one.

This check does not prove what the key may do. It asks whether the key reaches any newsletter at all, which is what POST /mcp asks too; every tool behind it then asks for a family at a level, so a key that passes here can still be refused by the tool your client called. If the check is green and the client is not, look at what the key was granted on the newsletter the tool was asked about. The refusal the assistant got names the missing area, and so does the assistant if you ask it what it can do on that newsletter.

A tool refused because it “does not say which” newsletter means the connection reaches several and has no default: name one in the request, or add ?newsletter= to the URL.

Asking POST /mcp directly is closer to the thing that is failing and worse at reporting on it: it needs a JSON-RPC envelope, a second Accept type, and it answers in server-sent events, so you would be reading a transport to find a credential answer.

Disconnecting#

Every application you connected is listed in Settings, Connected apps, and the ones reaching a newsletter are also on that newsletter's MCP page. Disconnecting one stops it on its next request. A key is revoked where you minted it, in Settings, API keys, and a newsletter's owner can also cut any key off that newsletter from its API page. Both take effect on the next request.

If you would rather write the requests yourself, Getting started covers the HTTP side of the same surface.