# Connect an AI assistant (MCP)

> Connect Claude, Claude Code or another MCP client to a Convia workspace, using a claude.ai connector or a workspace token, and check it works.

> For the complete documentation index, see [llms.txt](https://docs.conviapro.com/llms.txt).

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](https://docs.conviapro.com/docs/workspaces-and-teams.md).
- **The right plan.** The workspace's plan includes MCP Connections. If it does not, **MCP Connections** is missing from **Integrations**. See [Plans & billing](https://docs.conviapro.com/docs/plans-and-billing.md).
- **A client that speaks MCP over HTTP**, such as claude.ai, Claude Desktop or Claude Code.

> [!NOTE]
> To find the page, open the launcher at the bottom left, choose **Integrations** under **Workspace**, then **MCP Connections**. This page writes that as **Integrations → MCP Connections**.

## 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.

| Client | Credential | Token needed |
|---|---|---|
| claude.ai on the web, iPhone and Android, and Claude Desktop through the same connector | Sign in with your Convia account (OAuth) | No |
| Claude Code | Workspace token in an `Authorization` header | Yes |
| Claude Desktop through a config file | Workspace token, passed by a bridge | Yes |
| Other MCP clients | Workspace token, or OAuth if the client supports a pre-registered client ID | Usually |

## 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](https://docs.conviapro.com/docs/get-support.md) 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**.

> [!WARNING]
> Convia shows a token only once and cannot show it again. If you lose it, create a new token and revoke the old one.

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:

```bash
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`:

```json
{
  "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.

| Setting | Value |
|---|---|
| Transport | Streamable HTTP. Stateless: every request is a `POST` to the Server URL and every response is JSON |
| URL | `<your MCP URL>` |
| Header | `Authorization: Bearer mcp_live_…` |
| Protocol versions | `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05` |

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

```bash
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](https://docs.conviapro.com/docs/mcp-security.md).

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](https://docs.conviapro.com/docs/mcp-security.md#oauth-for-client-developers).

## 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](https://docs.conviapro.com/docs/brand-brain.md).
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](https://docs.conviapro.com/docs/troubleshooting.md) and [MCP access, permissions & audit](https://docs.conviapro.com/docs/mcp-security.md).

## 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](https://docs.conviapro.com/docs/mcp-workflows.md).

## 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](https://docs.conviapro.com/docs/mcp-tools.md): every tool, its parameters and what it returns.
- [Agent workflows](https://docs.conviapro.com/docs/mcp-workflows.md): recipes for drafting, campaigns, revisions and retractions.
- [MCP access, permissions & audit](https://docs.conviapro.com/docs/mcp-security.md): roles, plan, OAuth details, errors and the Activity log.
- [Convia for AI agents](https://docs.conviapro.com/docs/ai-agents-overview.md): what an agent can and cannot do in Convia.

---

Source: https://docs.conviapro.com/docs/mcp-quickstart · Section: AI agents & MCP · Last updated: 2026-10-03