# MCP server

> Connect Claude Code, Cursor and other AI tools to your intoCHAT account through its remote MCP server: the endpoint, API keys and scopes, setup for each client, the tools, and the limits.

intoCHAT has a remote MCP server. MCP (Model Context Protocol) is the standard way AI tools such as Claude Code and Cursor connect to other services. Once you connect yours, you can ask it in plain words to list your agents, read their conversations and leads, add text snippets and Q&A pairs, delete sources or send an agent a test message, and it calls intoCHAT for you.

The MCP server uses the same API keys, scopes, plan and rate limit as the [REST API](/en/docs/rest-api), and its tools do exactly what the matching REST endpoints do.

## Endpoint

```text
https://www.intochat.ai/api/mcp
```

The server uses the Streamable HTTP transport. Every request needs your API key in the `Authorization` header:

```text
Authorization: Bearer ic_live_YOUR_KEY
```

Use the address with `www`, as above.

> Sign-in with OAuth isn't supported yet. Clients that can only connect through OAuth, such as custom connectors in Claude.ai and the Claude desktop app, or connectors in ChatGPT, can't use the server for now. Clients that let you set a header work: Claude Code, Cursor, the MCP Inspector, and the Claude desktop app through a local bridge (see [Other clients](#other-clients)).

## Before you start

The MCP server is included on **Starter**, **Pro** and **Enterprise**, like the REST API. On **Free** you can't create API keys, and an account that moves back to Free gets an error on every request until it's on Starter or higher again.

You need an API key. Only the account owner and admins can create one.

## Create an API key

1. In the sidebar, under **Settings**, click **API keys**.
2. Under **Create a key**, give the key a **Name**, for example `Claude Code`.
3. Under **Access**, choose what the AI tool may do. **Every scope, including ones added later** allows every tool. To keep it read-only, pick **Only the scopes I choose** and tick only the `:read` scopes. See [Tools](#tools) for the scope each tool needs.
4. Click **Create key**, then **Copy**, and click **I've saved it**. The key is shown only once.

A key works for every agent in the account. Treat it like a password: keep it out of files you commit or share, and revoke it on the **API keys** page if someone else may have it. See [Create an API key](/en/docs/rest-api#create-an-api-key) in the REST API docs for more.

## Connect Claude Code

Run this in a terminal, with your key in place of `ic_live_YOUR_KEY`:

```bash
claude mcp add --transport http intochat https://www.intochat.ai/api/mcp \
  --header "Authorization: Bearer ic_live_YOUR_KEY"
```

This adds the server for the current project, on your computer only. To use it in every project, add `--scope user` before `--transport`.

To share the setup with your team in the project's `.mcp.json` without the key itself, read the key from an environment variable:

```json
{
  "mcpServers": {
    "intochat": {
      "type": "http",
      "url": "https://www.intochat.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${INTOCHAT_API_KEY}"
      }
    }
  }
}
```

Then type `/mcp` in Claude Code to check that **intochat** is connected, and ask, for example: "List my intoCHAT agents."

## Connect Cursor

In Cursor's settings, open the MCP section and add a server, or edit `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "intochat": {
      "url": "https://www.intochat.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ic_live_YOUR_KEY"
      }
    }
  }
}
```

The intoCHAT tools then appear in the list of MCP tools, and Cursor's agent can use them.

## Other clients

Any MCP client that supports the Streamable HTTP transport and lets you add a header can connect. Give it the [endpoint](#endpoint) and the `Authorization` header.

**Claude desktop app.** Its **Connectors** settings need OAuth, which isn't supported yet. Instead, add the server to `claude_desktop_config.json` through the open-source `mcp-remote` bridge, which needs Node.js on your computer:

```json
{
  "mcpServers": {
    "intochat": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.intochat.ai/api/mcp", "--header", "Authorization:${INTOCHAT_AUTH}"],
      "env": {
        "INTOCHAT_AUTH": "Bearer ic_live_YOUR_KEY"
      }
    }
  }
}
```

**MCP Inspector.** Run `npx @modelcontextprotocol/inspector`, choose **Streamable HTTP**, enter the endpoint and add the `Authorization` header. Connect through the Inspector's proxy: the server refuses requests made directly from a web page on another site.

**Testing with curl.** Every request is one JSON-RPC message in a POST:

```bash
curl https://www.intochat.ai/api/mcp \
  -H "Authorization: Bearer ic_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
```

The server speaks MCP versions `2026-07-28` and `2025-03-26` to `2025-11-25`, answers every request with JSON, and keeps no session between requests.

## Tools

| Tool | Scope | What it does |
| --- | --- | --- |
| `list_agents` | `agents:read` | Lists the account's agents with their IDs, training status and counts. |
| `get_agent` | `agents:read` | Gets one agent. |
| `chat_with_agent` | `chat` | Sends a message to an agent and returns its reply. Each reply counts as one message on your plan. |
| `list_conversations` | `conversations:read` | Lists an agent's conversations, newest first, without transcripts. |
| `get_conversation` | `conversations:read` | Gets one conversation with its transcript. |
| `list_leads` | `leads:read` | Lists the leads an agent collected, newest first. |
| `list_contacts` | `leads:read` | Lists an agent's [contacts](/en/docs/contacts), newest first, or looks one up by `email` or `external_id`. |
| `upsert_contact` | `contacts:write` | Creates or updates a contact by `external_id`, else `email`, with `phone`, `name` and `attributes` (an object; `null` removes an attribute). |
| `list_sources` | `sources:read` | Lists an agent's knowledge sources, its training progress and the characters it uses. |
| `add_text_source` | `sources:write` | Adds a text snippet with a title and starts training. |
| `add_qa_pair` | `sources:write` | Adds a question and answer and starts training. If the agent already has the same question, its answer is replaced. |
| `delete_source` | `sources:write` | Deletes a source and what the agent learned from it. This can't be undone. |

Each tool returns the same data as its REST endpoint, as JSON. `list_conversations`, `list_leads` and `list_contacts` take an optional `limit` (1 to 100), `cursor` and `since`, as described under [Pagination](/en/docs/rest-api#pagination).

The tools are marked as read-only or not, and `delete_source`, `add_qa_pair` and `upsert_contact` as able to change what's already there, so your AI tool can ask you before it uses them. Many AI tools ask for your confirmation before they run any tool.

If the key doesn't have the scope a tool needs, the tool answers with an error that names the scope, and nothing happens. An agent, conversation or source in another account is "not found", the same as one that doesn't exist.

There are no tools to create agents or change their settings or instructions. Do that in the dashboard.

## Chatting with an agent

`chat_with_agent` sends a real message, answered by the same code as the chat widget, from the agent's knowledge, instructions and actions. Use it to test how an agent answers.

- Each reply counts as one message on your plan and toward the agent's [monthly message cap](/en/docs/limits-and-access#monthly-message-cap), if you set one. See [What counts as a message](/en/docs/plans-and-limits#what-counts-as-a-message).
- Leave out `conversationId` to start a new conversation. To continue one, pass the `conversationId` from the earlier reply.
- The conversations appear on the agent's **Conversations** tab like any other.
- A private agent can't be reached this way. See [Private agents](/en/docs/allowed-domains#private-agents).

Ask your AI tool not to send many messages in a row unless you mean it to: each one uses your plan's messages.

## Limits

- **Plan:** Starter, Pro or Enterprise. On Free, requests are refused.
- **Rate limit:** 60 requests a minute per key, shared with the REST API. Connecting takes a few requests, and so does every tool call. Over the limit, requests are refused for the rest of the minute. A separate key for your AI tool keeps it from using your server's requests.
- **Messages:** each `chat_with_agent` reply counts as one message on your plan. A reply must finish within 55 seconds.
- **Sign-in:** API keys only. OAuth isn't supported yet, so clients that need it can't connect.
- **Sources:** text snippets and Q&A pairs only. Add website pages, files and Notion pages in the dashboard.
- **No live updates:** the server answers each request and doesn't push notifications.

If your client can't connect, check the error it shows: an invalid or revoked key is refused with `401`, an account on Free with `403`, and too many requests with `429`.

## Next steps

- Call intoCHAT from your own code: [REST API](/en/docs/rest-api).
- Get leads and hand-offs pushed to your server as they happen: [Webhooks](/en/docs/webhooks).
- Write good text snippets and Q&A pairs: [Text and Q&A](/en/docs/text-and-qa).