Skip to content
Convia ProDocs

For the complete documentation index, see llms.txt. This page is also available as markdown.

Connect an AI assistant (MCP)

Connect Claude, ChatGPT, Grok, Gemini CLI or another MCP client to your Convia workspaces at mcp.conviapro.com, check it works, and disconnect it.

Last updated
On this page

MCP Connections lets Claude and other Model Context Protocol (MCP) clients read and write your Convia Pro workspaces: draft posts, campaigns, ideas and scripts, and look things up across episodes, transcripts, posts and analytics. One address, https://mcp.conviapro.com, serves every workspace. An Owner or Manager connects a client with a claude.ai custom connector or a workspace token, then checks the call on the Activity tab.

Before you connect an MCP client

You need three things:

  • The right role. You are an Owner or Manager of each workspace you connect. Contributors and Viewers cannot connect. See Workspaces & teams.
  • The right plan. MCP Connections comes with Grow and above. Advanced MCP, on Scale and above, adds drafting up to 100 posts in one step and changing a video already on YouTube. If the plan does not include MCP Connections, the MCP Connections page shows a locked card. See Plans & billing.
  • A client that speaks MCP over HTTP, such as claude.ai, ChatGPT, Grok, Claude Desktop, Claude Code or Gemini CLI.

The Convia MCP URL

Every client connects to the same address:

text
https://mcp.conviapro.com

It is also shown as the Server URL under How to connect a client on Integrations → MCP Connections. Which workspaces a connection reaches depends on how it signs in:

  • A claude.ai connector reaches the workspaces you tick when you approve it.
  • A workspace token reaches the workspace it was created in.

Connectors you set up before, with an address ending in a workspace id, keep working.

Choose how your MCP client signs in

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
ChatGPT on the web and the desktop app Sign in with your Convia account (OAuth) No
Grok Sign in with your Convia account (OAuth) No
Other assistants with custom connectors Sign in with your Convia account (OAuth), after you tick I trust for the assistant No
Gemini CLI 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 OAuth if the client registers itself, otherwise a workspace token Depends on the 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, and can reach several of your workspaces.

  1. In Claude, add a custom connector with the address https://mcp.conviapro.com. Leave OAuth Client ID and Client Secret under Advanced settings empty: Claude registers itself with Convia.
  2. Save the connector. Claude sends you to Convia to sign in.
  3. On Convia's Connect screen, check Signed in as (the account you're using) and Sends you back to (the assistant's address, such as claude.ai).
  4. Under Workspaces it can use, tick the workspaces Claude may use. The list shows those you own or manage on a plan that includes MCP Connections, up to 25 per connection.
  5. Click Approve.

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

What changes when a connector reaches several workspaces

With one workspace ticked, Claude works on that workspace with no extra step. With more than one, Claude names the workspace on every request, can list the workspaces it has, and every answer says which workspace it came from. A request that names no workspace, or one it was not given, is refused rather than guessed, so a post never lands in the wrong show.

To change which workspaces a connector reaches, remove the connector in Claude and add it again, then tick the new set.

Connecting an app Convia does not recognize

If Sends you back to is not an assistant Convia recognizes (Claude, ChatGPT and Grok are), the Connect screen warns you and asks you to tick I trust followed by that address before you can approve. Deny it if you did not start the connection yourself. An app you trust this way connects for you only, and is listed on the Apps you trusted tab. See MCP access, permissions & audit.

Connect ChatGPT

ChatGPT signs in the same way as a claude.ai connector, so there is no token to copy. Custom connectors in ChatGPT need developer mode, on the ChatGPT plans that offer it.

  1. In ChatGPT, open Settings, then Apps & Connectors. Turn on developer mode under Advanced settings if it is off.
  2. Create a connector, paste https://mcp.conviapro.com as the server address and choose OAuth.
  3. ChatGPT sends you to Convia. On the Connect screen, tick the workspaces ChatGPT may use and click Approve.
  4. In the desktop app, sign-in ends on a page that says Authentication complete. Close it and go back to ChatGPT.

Connect Grok

Grok signs in the same way as a claude.ai connector, so there is no token to copy.

  1. In Grok, open Connectors, add a new custom connector and paste https://mcp.conviapro.com as its address.
  2. Grok sends you to Convia. On the Connect screen, check that Sends you back to says grok.com, tick the workspaces Grok may use and click Approve.

Connect other assistants

Any assistant that lets you add a custom MCP connector by its address, and registers itself with the server, can connect with your Convia account. Menus differ between assistants and change often, so follow the assistant's own help for where to add one.

  1. In the assistant, add a custom connector with the address https://mcp.conviapro.com. If it asks for an OAuth Client ID, leave it empty or choose automatic registration.
  2. The assistant sends you to Convia to sign in.
  3. Convia recognizes Claude, ChatGPT and Grok, so for any other assistant the Connect screen shows a warning with its address under Sends you back to. Check that it is the assistant you are connecting, then tick I trust followed by that address. See Connecting an app Convia does not recognize.
  4. Tick the workspaces the assistant may use and click Approve.

An assistant that only works with a Client ID and secret it was given in advance cannot sign in to Convia this way. The Gemini app is one: its custom connectors ask for both. Use Gemini CLI instead (below), or a workspace token in any client that lets you set an Authorization header; see Connect another MCP client.

Gemini CLI

Gemini CLI registers itself and signs in through your browser, so it needs no token and no I trust tick. Add Convia to ~/.gemini/settings.json:

json
{
  "mcpServers": {
    "convia": {
      "httpUrl": "https://mcp.conviapro.com"
    }
  }
}

Start Gemini CLI and run /mcp auth convia. Your browser opens on Convia's Connect screen: tick the workspaces and click Approve, then go back to the terminal.

Create a workspace token

Claude Code, a Claude Desktop config file and some other clients use a workspace token. Tokens start with mcp_live_ and reach only the workspace they were created in.

  1. Switch to the workspace the token is for.
  2. Open Integrations → MCP Connections and click the Tokens tab.
  3. Click New token (or Create your first token if you have none).
  4. Enter a Name that says where the token will live, such as "Claude Desktop, laptop".
  5. Choose Expires: Never, 30 days or 90 days.
  6. Click Create token.
  7. 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.
  8. 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 MCP URL directly over HTTP and sends your token as a header. Run this in your terminal, with your own token:

bash
claude mcp add --transport http convia https://mcp.conviapro.com \
  --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 the MCP 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", "https://mcp.conviapro.com", "--header", "Authorization:${CONVIA_MCP_TOKEN}"],
      "env": {
        "CONVIA_MCP_TOKEN": "Bearer mcp_live_…"
      }
    }
  }
}
  1. 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 MCP URL and every response is JSON
URL https://mcp.conviapro.com
Header Authorization: Bearer mcp_live_…, or an OAuth access token
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 "https://mcp.conviapro.com" \
  -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 the tools your plan includes. A 401 means the credential is wrong, revoked or expired; a 403 means the membership, role, plan or workspace check failed. Both are explained in MCP access, permissions & audit.

Clients that implement OAuth discover Convia's sign-in from the 401 and register themselves. Details are in MCP access, permissions & audit.

Check that the MCP connection works

  1. In your client, ask: "Use Convia to summarize my brand voice." On a connector with several workspaces, name the show.
  2. The assistant should call get_brand_context and describe your Brand Brain.
  3. In Convia, switch to that workspace, 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 MCP 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."
  • "What's stuck? List the posts waiting on someone, most urgent first."
  • "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."

On a connector with several workspaces, say which show each prompt is for. For step-by-step patterns an agent can follow, see Agent workflows.

Disconnect an app from a workspace

The Connected apps tab lists the apps connected to the workspace you're in, who connected each one and when it was last used. Owners and Managers see everyone's connections; anyone else sees their own.

  1. Switch to the workspace and open Integrations → MCP Connections. Connected apps is the first tab.
  2. Open the row's menu and choose Disconnect from this workspace.
  3. Confirm with Disconnect.

The app stops reaching that workspace at its next request. Its other workspaces are not affected, and this cannot be undone: to give it the workspace back, remove the connector in the app and add it again. To stop a person using MCP altogether, change their role.

Revoke an MCP 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.