Connect AI Assistants (MCP)

Your AI Connector ships an official MCP server — a Model Context Protocol endpoint that lets AI assistants like Claude Code, Claude Desktop, Cursor, and your own apps drive your Your AI Connector account directly. Ask in plain language (“list my AI agents”, “add this lead”, “what did AI cost me this week?”) and the assistant calls the Your AI Connector API for you.

It’s the same v1 API you reach with an API key, authenticated with your own API key. The MCP server builds one tool for each operation in our published API specification, so it covers most, but not all, of the v1 API: contacts, messages, campaigns, AI agents, custom functions, knowledge base, appointments, analytics, tags, lists, broadcasts, deals, channel connections and sub-accounts. Automations can be listed and read, but not created or edited through MCP yet; build those in the app. Within what it exposes there are no per-tool permissions and no read-only default, so the API key is the whole access control.

Endpoint: https://mcp.youraiconnector.com/mcp
Auth: your Your AI Connector API key (sent as the X-API-Key header)
Requires: a plan with API access. Create an API key →

Your API key acts on your own account, with the same permissions as the rest of the API — and can read the client accounts you manage, if you’re on an agency plan (see below). Treat it like a password. You can revoke it any time from Settings → Integrations → API Key, which instantly cuts off the assistant’s access.

Claude Code

claude mcp add --transport http ai-connector https://mcp.youraiconnector.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"

Then run /mcp inside Claude Code to confirm it shows ai-connector ✓ connected.

By default the server is added at the local scope (just you, this project). Use --scope user to make it available in all your projects, or --scope project to commit it to a repo’s .mcp.json for your team:

{
  "mcpServers": {
    "ai-connector": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}

Claude Desktop

Add the server as a custom connector. It is set up in your Claude account, so it works in Claude Desktop and on claude.ai alike (free Claude accounts can add one custom connector).

Open Customize → Connectors, click + Add, then Add custom connector.
Give it a name and enter https://mcp.youraiconnector.com/mcp as the URL.
Under Authentication, choose No sign in. The MCP server has no sign-in page: picking a sign-in option ends in “Couldn’t register with … sign-in service”.
Under Request headers, add a header named X-API-Key with your API key as the value.
Click Add. Your AI Connector tools appear in the tools menu of a new chat.

No Request headers field? Your Claude Desktop version is older: update it, or use the config file instead. The config file (claude_desktop_config.json, Settings → Developer → Edit Config) only runs programs on your computer and ignores a url entry, so it needs the small mcp-remote bridge, which requires Node.js 18 or newer:

{
  "mcpServers": {
    "ai-connector": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.youraiconnector.com/mcp",
        "--header",
        "X-API-Key:${AI_CONNECTOR_KEY}"
      ],
      "env": { "AI_CONNECTOR_KEY": "YOUR_API_KEY" }
    }
  }
}

Keep X-API-Key:${AI_CONNECTOR_KEY} exactly as written, with no space after the colon (on Windows a space splits the header), and put your key only in env. Then fully quit Claude Desktop (on Windows, right-click the tray icon → Quit) and open it again.

ChatGPT

ChatGPT cannot connect to the MCP server at the moment. Its custom connector form only offers OAuth or No authentication, and the Your AI Connector MCP server signs in with your API key, sent as a request header. Choosing OAuth fails with “could not discover OAuth settings”, and No authentication is refused because every request needs the key.

Use an assistant that lets you set a request header instead: Claude Code, Claude Desktop, Cursor or another MCP client, or the Claude API.

ChatGPT can still read the help docs without a connection: see The help docs are built in for the public llms.txt files.

Cursor & other MCP clients

Most MCP-capable editors use the same .mcp.json shape shown above (an HTTP server with a url and an X-API-Key header). Add a ai-connector server pointing at https://mcp.youraiconnector.com/mcp and paste your API key in the header.

The Claude API (build it into your own app)

You can connect the MCP server programmatically with the Claude API’s MCP connector, so an agent you build can use Your AI Connector tools without a separate client:

{
  "model": "claude-opus-4-8",
  "messages": [{ "role": "user", "content": "List my AI agents" }],
  "mcp_servers": [
    {
      "type": "url",
      "name": "ai-connector",
      "url": "https://mcp.youraiconnector.com/mcp",
      "authorization_token": "YOUR_API_KEY"
    }
  ]
}

What you can do

Within the part of the v1 API the MCP server exposes, the assistant picks the right tool automatically:

AI agents: list, create, update, pause/resume, inspect configuration.
Contacts: search, create, tag, add to lists, import.
Knowledge base / FAQs: add, edit, bulk import, approve AI suggestions.
Messages: read conversations, send a message to a contact.
Appointments: list, book, cancel.
Tasks: create, complete, list.
Analytics: message stats, credit usage, AI cost.
Channels: check connection status, start a connection flow.

Asking about your clients’ accounts (agencies)

One connection covers every account you manage. You don’t add a second connection per client: on an agency plan, the assistant can read any client account under you, so you can ask about all of them in one conversation.

Just name the client:

“How many contacts does Bella’s Bistro have?”
“What did AI cost each of my clients this week?”
“What’s the state of Northside Dental’s channels, and how many chats came in this week?”

This covers reading contacts, messages, chats, campaigns, appointments, tasks, tags, events, FAQs, knowledge base sources, phone numbers, channels, webhooks and analytics. We check the account really is yours before anything runs — asking for one that isn’t comes back as “not found”. Leave the client out and the assistant reads your own account, exactly as before.

Changing a client’s account works the same way. Every action that accepts a client account in the API is available for a named client: setting up AI agents, knowledge base, custom functions, WhatsApp templates, entry points, channel connections, contacts, tags, broadcasts, appointments, deals and tasks, and sending messages. The exceptions are agency-level actions, which always run on your own agency account: managing the client accounts themselves (limits, features, pricing, pausing), snapshots, your team and API keys. Adding contacts to or removing them from a client’s list is not available for a named client yet; do that from that client’s own key or in their account. The agency API guide lists what is supported.

The agency tools are only on the standard, unbranded address, https://mcp.youraiconnector.com/mcp. A white-label MCP address on your own domain (mcp.youragency.com) is built for your clients and leaves them out, so connect with the standard, unbranded address when you manage client accounts.

This is also the answer for a client who runs several businesses under one login. Give each business its own account, then invite the client’s email as a team member on all of them: they sign in once and switch between their brands with the account picker in the sidebar.

Testing a client’s agent

Ask the assistant to try out a client’s agent (“send ‘do you deliver on Sundays?’ to the Bakery agent of client X and show me what it did”). It sends a Try Out message with your agency key and the client’s sub_account_id, waits, and reads back the reply plus any actions the agent took. No copy of the agent is needed. If the assistant says you are not an agency account, it is connected with a client’s key: reconnect it with your agency account’s key. See Try Out.

Clients with a tool limit

Some AI clients only accept a server with a limited number of tools. Composio, for example, refuses a server that lists more than 500 tools and imports none of them. The full agency connection lists more than that, so add ?tags= to the address with only the groups of tools you need.

For an agency that wants to list its client accounts, read their contacts, chats and messages, and send messages:

https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages

That loads about 80 tools. Name the client in your request and the assistant acts on that client’s account, as described above.

Separate groups with commas; upper or lower case both work.
To add single tools, list their exact names with tools=, for example ?tags=Contacts&tools=list_or_get_subaccounts. You get every tool from either list.
The help docs tools are always included.
The API key still goes in the X-API-Key header (or Authorization: Bearer YOUR_API_KEY), never in the address.

The help docs are built in

The MCP server gives the assistant your account and this documentation. Three tools read the help docs live, so the assistant can look up how a feature works, or what changed recently, instead of guessing:

docs_search: finds the sections that answer a question and returns them with the page link.
docs_read: reads one page in full, or one section of it.
docs_list: lists every page by area.

There is nothing to set up, and the docs tools never touch your account data. Ask “how do entry points work?” or “what is new in automations?” and the assistant searches the docs first. Because the tools read the help site itself, a feature is known to your assistant as soon as its guide is published.

An assistant that is not connected through MCP can still read the docs: point it at https://docs.youraiconnector.com/llms.txt (an index of every help page with a link to each page’s Markdown version) or https://docs.youraiconnector.com/llms-full.txt (the whole documentation in one Markdown file). Both are public, need no key, and are rebuilt with every documentation change.

Finding or Generating Your API Key

The API key this connection uses lives at Settings → Integrations → API Key — its own section, separate from Webhooks. See API Access for the exact steps.

Troubleshooting

“Connection refused” or “not found” — the address is missing the /mcp at the end. Use https://mcp.youraiconnector.com/mcp, not https://mcp.youraiconnector.com.
Needs authentication / 401 — your API key is missing or wrong. Re-add the server with a valid X-API-Key.
“Could not discover OAuth settings” (ChatGPT) — ChatGPT only supports OAuth or no authentication for custom connectors, and the MCP server uses an API key, so ChatGPT cannot connect for now. See ChatGPT.
“Couldn’t register with … sign-in service” or “add an OAuth Client ID” (Claude Desktop) — the custom connector was added with a sign-in option. There is no OAuth client ID to enter: remove the connector and add it again with Authentication → No sign in and your API key as an X-API-Key request header, as in Claude Desktop.
Claude Desktop shows no tools after editing the config file — the config file ignores a "url" entry; use the custom connector or the mcp-remote form in Claude Desktop, and fully quit and reopen the app.
A tool returns 403 — your plan or team role doesn’t permit that action; the MCP server enforces nothing extra, it’s the same permission check as the API.
Tool not found — the tool list is generated live from the API, so it always matches the current version; reconnect to refresh.
A security or certificate warning on your own domain — pointing a DNS record at us isn’t enough on its own: the subdomain also has to be verified in the dashboard before it can serve a secure connection. White-label agencies can put the MCP address on their own domain (e.g. mcp.youragency.com) from the Custom domain card under Settings → White Labeling — add the CNAME at your registrar first, then enter the hostname in the MCP domain (AI assistants) block and click Verify, the same flow as your other branded subdomains. The branded address leaves out the agency tools; keep using the standard, unbranded address for those. Until your branded address is verified, use the standard, unbranded address: it is safe to share with clients.

Next Steps

API Access — generate or rotate the key this connection uses.
Webhooks — the push-based counterpart to this pull-based MCP connection.

Connect AI Assistants (MCP) #

Claude Code #

Claude Desktop #

ChatGPT #

Cursor & other MCP clients #

The Claude API (build it into your own app) #

What you can do #

Asking about your clients’ accounts (agencies) #

Testing a client’s agent #

Clients with a tool limit #

The help docs are built in #

Finding or Generating Your API Key #

Troubleshooting #

Next Steps #