> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osis.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect over MCP

> Point Claude, Cursor, ChatGPT, or any MCP client at your Comms workspace — sign in with OAuth or use an API key.

Connect your own AI (Claude, ChatGPT, Cursor, or any MCP-capable client) to your Comms workspace. Over MCP you can read and reply to conversations, send messages, and manage agents — the same surface the dashboard exposes for automation.

There are two ways to authenticate: **sign in with OAuth** (no key to copy — the client walks you through consent) or a **Messages API key** in an Authorization header. Either way, what the connection can do is controlled by its [scopes](/messages-api/authentication#scopes).

## Endpoint

```text theme={null}
https://comms.osis.co/api/v1/comms/mcp
```

## Sign in with OAuth (claude.ai and Claude Desktop)

Comms implements the MCP authorization spec, so clients that support it connect without any key handling:

1. In claude.ai (or Claude Desktop), go to **Settings → Connectors → Add custom connector**.
2. Paste the endpoint above and add it.
3. The client discovers Comms' authorization server, registers itself, and opens a sign-in window.
4. Sign in to your Comms account and review the consent screen — it lists the app requesting access and the scopes it will get, each as a checkbox you can uncheck.
5. Approve. The client receives a workspace-scoped token and refreshes it automatically; no secret ever passes through you.

Claude Code works the same way with no header:

```bash theme={null}
claude mcp add --transport http comms https://comms.osis.co/api/v1/comms/mcp
```

The first tool call triggers the same browser sign-in and consent flow.

## Connect with an API key

For headless clients, servers, or anywhere a browser sign-in doesn't fit, use a Messages API key from **[Developers](https://comms.osis.co/dashboard/api)** (or [API keys](https://comms.osis.co/dashboard/settings/api-keys)). Authenticate every request with the key:

```http theme={null}
Authorization: Bearer osis_…
```

Claude Code with an explicit key:

```bash theme={null}
claude mcp add --transport http comms https://comms.osis.co/api/v1/comms/mcp --header "Authorization: Bearer <your API key>"
```

Replace `<your API key>` with a full `osis_…` secret (not the truncated prefix shown in the dashboard).

## Other clients

Any MCP client that supports streamable HTTP (or HTTP transport) works. Clients that implement MCP authorization can just point at the endpoint and sign in; the rest take a bearer header:

| Client                     | What to set                                                                                    |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| **ChatGPT**                | Custom connector URL = endpoint above; completes the OAuth sign-in, or accepts a bearer header |
| **Cursor**                 | MCP server URL = endpoint above; OAuth sign-in, or header `Authorization: Bearer osis_…`       |
| **Claude Desktop / other** | HTTP MCP server pointing at the endpoint                                                       |

Use the same endpoint everywhere; only the client’s config UI differs.

## Scopes

| Scope            | Typical MCP use                                       |
| ---------------- | ----------------------------------------------------- |
| `comms_read`     | Conversations, messages, contacts, analytics          |
| `comms_send`     | Send messages and announcements to customers          |
| `comms_write`    | Conversation state, contacts, lists                   |
| `comms_manage`   | Agents, knowledge, lines, templates, workspace config |
| `comms_webhooks` | Manage event subscriptions                            |

Grant least privilege per client: with OAuth, uncheck scopes on the consent screen; with keys, mint a dedicated key — for example read-only for research agents, send + read for an ops assistant.

## Security

<Warning>
  Treat the API key like a production secret. Prefer a dedicated key per MCP client so you can revoke one without breaking backends. Never paste keys into shared chats or commit them to git. OAuth connections carry no long-lived secret you handle — tokens are workspace-scoped, expire on their own, and refresh behind the scenes.
</Warning>

## Next steps

* [Authentication](/messages-api/authentication) — scopes, rotation, and rate limits.
* [Send a message](/messages-api/send-message) — REST equivalent of outbound tools.
* [Webhooks](/guides/webhooks) — push events when you prefer HTTP callbacks over polling.