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

# Connect with MCP

> Connect an MCP client to Communicate's authenticated Streamable HTTP endpoint.

The remote MCP endpoint is:

```text theme={null}
https://app.communicate.so/mcp
```

Version `0.1.5` supports SDK v1 and SDK v2 clients, including legacy `2025-11-25` and modern `2026-07-28` protocol revisions. Workspace OAuth tokens retain the read-only `communicate_list_agents` tool. Explicitly MCP-bound account credentials expose the registered management tools allowed by their live scopes.

## Create an MCP management credential

Use the [CLI bootstrap workflow](/docs/cli#authenticate-without-a-browser) with a private input file containing verified email/password proof, a credential name, the scopes your workflow needs, and this explicit audience:

```json theme={null}
{
  "audience": "https://app.communicate.so/mcp",
  "scopes": ["workspaces:read", "agents:read", "sources:read", "sources:write"]
}
```

This fragment supplies the audience and scopes; include the remaining required bootstrap fields from command help. Store the one-time token in a protected output file or secret manager, then configure it as `COMMUNICATE_MCP_TOKEN`. Account credentials expire within 24 hours and cannot outlive their issuer session.

| Management workflow | Required scope |
| - | - |
| Workspace discovery and creation | `workspaces:read`, `workspaces:write` |
| Workspace settings and membership | `workspaces:manage`, `members:read`, `members:write` |
| Agent discovery/configuration, actions and campaigns | `agents:read`, `agents:write` |
| Source creation, upload, reading, editing and removal | `sources:read`, `sources:write` |
| Learning and Grill workflows | `learnings:read`, `learnings:write`, `grill:read`, `grill:write` |
| Personal notification settings and devices | `notifications:read`, `notifications:write` |

Each tool declares its input/output schema. Missing scopes remove tools from discovery; native membership, role, agent access and entitlement checks still apply. Writes are never automatically retried. Source file uploads take `{ "file": { "name": "guide.txt", "base64": "..." } }` plus workspace/agent IDs, with a 10 MB decoded limit. The server does not read filesystem paths.

REST-bound `ca_` credentials and REST OAuth tokens cannot call MCP. Existing `ck_` workspace secrets never gain account management permissions automatically. Coverage remains partial; billing, inbox/prospect reply and other unfinished workflows are not established by this increment.

## Legacy read-only workspace OAuth

Create an API key with `agents:read`, then exchange its client ID and one-time `ck_` secret for a token bound to the MCP resource.

```bash theme={null}
export COMMUNICATE_CLIENT_ID="your_key_id"
export COMMUNICATE_CLIENT_SECRET="ck_your_secret"

export COMMUNICATE_MCP_TOKEN="$(curl -sS \
  -u "$COMMUNICATE_CLIENT_ID:$COMMUNICATE_CLIENT_SECRET" \
  https://app.communicate.so/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "scope=agents%3Aread" \
  -d "resource=https%3A%2F%2Fapp.communicate.so%2Fmcp" \
  | jq -r '.access_token')"
```

The token expires after one hour. Request a new token before reconnecting after expiry.

## Configure your client

Use Streamable HTTP and send the token as a bearer credential:

```json theme={null}
{
  "mcpServers": {
    "communicate": {
      "url": "https://app.communicate.so/mcp",
      "headers": {
        "Authorization": "Bearer ${COMMUNICATE_MCP_TOKEN}"
      }
    }
  }
}
```

For Codex, use the equivalent environment-backed bearer token setting:

```toml theme={null}
[mcp_servers.communicate]
url = "https://app.communicate.so/mcp"
bearer_token_env_var = "COMMUNICATE_MCP_TOKEN"
```

<Warning>
  Do not place the client secret or bearer token directly in a committed configuration file. The endpoint does not accept long-lived `ck_` secrets.
</Warning>

## OAuth discovery

MCP clients can discover the authentication contract from:

```text theme={null}
https://app.communicate.so/.well-known/oauth-protected-resource/mcp
https://app.communicate.so/.well-known/oauth-authorization-server/api/v1
```

Workspace OAuth MCP tokens accept only `agents:read`; this restriction does not apply to explicitly scoped MCP account credentials. Use a separate REST token with `chat:write` for [agent conversations](/agents/rest-workflows).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.