Connect an AI assistant (MCP)

MCP Connections lets Claude and other Model Context Protocol (MCP) clients read and write one Convia Pro workspace: draft posts, campaigns, ideas and scripts, and look things up across episodes, transcripts, posts and analytics. This page walks an Owner or Manager through connecting a client and checking that it works.

Before you connect

You need three things:

• The right role. You are an Owner or Manager of the workspace. Contributors and Viewers cannot connect. See Workspaces & teams.
• The right plan. The workspace's plan includes MCP Connections. If it does not, MCP Connections is missing from Integrations. See Plans & billing.
• A client that speaks MCP over HTTP, such as claude.ai, Claude Desktop or Claude Code.

Find your MCP URL

Each workspace has its own MCP URL, and it ends with that workspace's ID. A connection to one workspace cannot reach another, so connect once per workspace.

1. Switch to the workspace you want to connect.
2. Open Integrations → MCP Connections.
3. Expand How to connect a client at the bottom of the card.
4. Copy the Server URL shown in the setup instructions. Always copy it from here rather than typing or reusing one from another workspace.

On this page, <your MCP URL> stands for that Server URL and mcp_live_… stands for a token.

Choose how to sign in

Convia accepts two kinds of credential. Pick by client.

Connect claude.ai with a custom connector

A custom connector signs you in with your normal Convia account, so there is no token to copy. One connector covers Claude on the web, your phone and Claude Desktop.

1. In Integrations → MCP Connections, expand How to connect a client and find the claude.ai, iPhone and Android entry. Note the Server URL and the OAuth Client ID.
2. In Claude, add a custom connector.
3. Paste the Server URL.
4. Open Advanced settings and enter the OAuth Client ID. Leave Client Secret blank.
5. Save the connector. Claude sends you to Convia to sign in.
6. On the Connect screen, read what the client is asking for and click Approve.

You should see the connector listed as connected in Claude, with Convia's tools available in a new conversation.

If the instructions say ask your workspace admin instead of showing an OAuth Client ID, contact support for the ID. claude.ai connectors do not accept workspace tokens, but Claude Code and a Claude Desktop config file do.

Create a workspace token

Claude Code, a Claude Desktop config file and most other clients use a workspace token. Tokens start with mcp_live_.

1. Open Integrations → MCP Connections and stay on the Tokens tab.
2. Click New token (or Create your first token if you have none).
3. Enter a Name that says where the token will live, such as "Claude Desktop, laptop".
4. Choose Expires: Never, 30 days or 90 days.
5. Click Create token.
6. In Your MCP token, copy the Token and the Server URL. The dialog also shows ready-to-paste setup for each client under Connect a client, with your token filled in.
7. Tick I have saved this token in a safe place, then click Close.

The token now appears in the Tokens list with its first characters, when it was created, when it was last used and when it expires.

Connect Claude Code

Claude Code connects to the Server URL directly over HTTP and sends your token as a header. Run this in your terminal, with your own URL and token:

claude mcp add --transport http convia <your MCP URL> \
  --header "Authorization: Bearer mcp_live_…"

Then run /mcp inside Claude Code, or claude mcp list in your terminal. You should see convia listed as connected.

Connect Claude Desktop with a config file

Claude Desktop runs MCP servers from its config file as local processes, so the config uses the mcp-remote bridge to reach your Server URL. This needs Node.js installed, because it runs through npx. You can skip this section if you added the claude.ai connector, which also works in Claude Desktop.

1. Open claude_desktop_config.json.
2. Add a convia entry under mcpServers:

{
  "mcpServers": {
    "convia": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "<your MCP URL>", "--header", "Authorization:${CONVIA_MCP_TOKEN}"],
      "env": {
        "CONVIA_MCP_TOKEN": "Bearer mcp_live_…"
      }
    }
  }
}

3. Save the file and restart Claude Desktop.

Keep Authorization:${CONVIA_MCP_TOKEN} exactly as written, with no space after the colon, and put the space inside the variable (Bearer mcp_live_…). Some clients split arguments on spaces, which breaks a header written with one.

Connect another MCP client

Any client that supports the Streamable HTTP transport can connect.

To check the endpoint by hand, send an initialize request:

curl -s -X POST "<your MCP URL>" \
  -H "Authorization: Bearer mcp_live_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

A working connection returns a result with serverInfo named convia-mcp and the server's instructions. Send {"jsonrpc":"2.0","id":2,"method":"tools/list"} the same way to see every tool. A 401 means the token is wrong, revoked or expired; a 403 means the membership, role or plan check failed. Both are explained in MCP access, permissions & audit.

Clients that implement OAuth can use it instead of a token if they let you enter a client ID. Discovery details are in MCP access, permissions & audit.

Check that it works

1. In your client, ask: "Use Convia to summarize my brand voice."
2. The assistant should call get_brand_context and describe your Brand Brain.
3. In Convia, open Integrations → MCP Connections and click the Activity tab. You should see the call listed with its tool name, a Success result and its latency.

If nothing appears in Activity, the request was refused before any tool ran. See Troubleshooting and MCP access, permissions & audit.

First prompts to try

These prompts use read tools first, then write drafts. Nothing is published: anything the assistant writes lands as a draft for you to review.

• "List my last five episodes and tell me which ones have a transcript but no posts yet."
• "Find what the guest said about pricing in our latest episode, with timestamps."
• "Which clips have never been posted to LinkedIn? Suggest three to resurface."
• "Draft a LinkedIn post about our latest episode in my brand voice. Check every quote against the transcript, and save it as a draft."
• "Show me what is on the calendar for the next two weeks."
• "Plan a two-week campaign around this episode's main argument and save it as a draft campaign."

For step-by-step patterns an agent can follow, see Agent workflows.

Revoke a token

Revoke a token when a device is lost, a person leaves, or you no longer use a client.

1. Open Integrations → MCP Connections, Tokens tab.
2. Click Revoke on the token's row.
3. Confirm with Revoke token.

Any client using that token stops working immediately. Revoking cannot be undone. Turn on Show revoked to see revoked and expired tokens, marked Revoked or Expired.

A claude.ai connector has no token to revoke. To disconnect it, remove the connector in Claude.

Related

• MCP tool reference: every tool, its parameters and what it returns.
• Agent workflows: recipes for drafting, campaigns, revisions and retractions.
• MCP access, permissions & audit: roles, plan, OAuth details, errors and the Activity log.
• Convia for AI agents: what an agent can and cannot do in Convia.