# Connect AI Assistants (MCP)

<span data-t="appName">Your AI Connector</span> 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 <span data-t="appName">Your AI Connector</span> 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 <span data-t="appName">Your AI Connector</span> API for you.

It's the same v1 API you reach with an [API key](api-access.md), 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 <span data-t="appName">Your AI Connector</span> API key (sent as the `X-API-Key` header)
- **Requires:** a plan with API access. [Create an API key →](api-access.md#generating-your-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



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

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

1. Open **Customize → Connectors**, click **+ Add**, then **Add custom connector**.
2. Give it a name and enter `https://mcp.youraiconnector.com/mcp` as the URL.
3. 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".
4. Under **Request headers**, add a header named `X-API-Key` with your API key
   as the value.
5. Click **Add**. <span data-t="appName">Your AI Connector</span> 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](https://nodejs.org) 18 or newer:

```json
{
  "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 <span data-t="appName">Your AI Connector</span> 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-code), [Claude Desktop](#claude-desktop),
[Cursor or another MCP client](#cursor--other-mcp-clients), or
[the Claude API](#the-claude-api-build-it-into-your-own-app).

ChatGPT can still read the help docs without a connection: see
[The help docs are built in](#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 <span data-t="appName">Your AI Connector</span> tools without a separate
client:

```json
{
  "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](../agency/api-for-agencies.md#where-sub_account_id-is-supported)
lists what is supported.

::: neutral-mcp
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](../chats/playground.md#testing-an-agent-from-the-api-or-an-ai-assistant).

## Clients with a tool limit

::: neutral-mcp
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](api-access.md#generating-your-api-key) 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](#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).
- **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](#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](api-access.md) — generate or rotate the key this connection uses.
- [Webhooks](webhooks.md) — the push-based counterpart to this pull-based MCP connection.