# MCP for AI assistants

MCP (Model Context Protocol) is a way to give an AI assistant our data. Connect the datool.ru server, and the assistant will find a channel, look at its statistics and posts and answer a question like “how did @rbc grow in October”.

## Address and key

- Server address: `https://api.datool.ru/v1/mcp/` (MCP over HTTP, “Streamable HTTP”).
- The key is the same as for the API: the `Authorization: Bearer dtk_your_key` header. Keys are created on the “API keys” page in your account.

!!! note
    The assistant uses requests just like your code: each tool call costs as many units as the API method, and it can access the same data as your plan. Directories and `/v1/me/` are free.

## Claude Code

```bash
# add the datool server to Claude Code; the key is from the "API keys" page in your account
claude mcp add --transport http datool https://api.datool.ru/v1/mcp/ \
  --header "Authorization: Bearer dtk_your_key"
```

## Cursor and other clients

Add the server to the MCP settings (in Cursor — the `.cursor/mcp.json` file):

```json
{
  "mcpServers": {
    "datool": {
      "url": "https://api.datool.ru/v1/mcp/",
      "headers": { "Authorization": "Bearer dtk_your_key" }
    }
  }
}
```

For Claude Desktop and other clients that can only run a local program, use the `mcp-remote` adapter (Node.js is required). In Claude Desktop the setting is the `claude_desktop_config.json` file (Settings → Developer → Edit Config). The key goes through an environment variable: a space inside an argument breaks the setting on Windows.

```json
{
  "mcpServers": {
    "datool": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.datool.ru/v1/mcp/",
               "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer dtk_your_key" }
    }
  }
}
```

## Tools

The tools are the API methods that read data, with the same names and parameters as in the [method reference](/en/api/methods/):

| Tool | What it does |
|---|---|
| `me_retrieve` | who I am, plan and remaining requests |
| `max_channels_resolve_retrieve` | find a channel by link, @handle or MAX ID |
| `max_channels_list` | channel catalog with filters |
| `max_channels_retrieve` | channel card |
| `max_stats_daily_list` | daily statistics |
| `max_channels_posts_retrieve` | channel posts |
| `max_posts_retrieve` | a single post |
| `max_categories_list`, `max_territories_list` | category and territory directories |

Nothing can be changed via MCP — for example, webhooks are managed only via the API with a “read and write” key.

## How it works inside

You can write your own MCP client without ready-made tools: the server accepts JSON-RPC 2.0 in a POST request and responds with JSON.

```bash
# the list of tools (free)
curl -X POST https://api.datool.ru/v1/mcp/ \
  -H "Authorization: Bearer dtk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

# call a tool: the @citynews channel card (costs as the API method — 1 unit)
curl -X POST https://api.datool.ru/v1/mcp/ \
  -H "Authorization: Bearer dtk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "max_channels_retrieve", "arguments": {"channel": "citynews"}}}'
```

A tool call response is the API method response as text (`content`) and as an object (`structuredContent`):

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{"type": "text", "text": "{\"id\": 4821, \"title\": \"Городские новости\", …}"}],
    "structuredContent": {"id": 4821, "title": "Городские новости", "subscribers": 128450},
    "isError": false
  }
}
```

| Protocol method | What it does |
|---|---|
| `initialize` | Handshake: protocol version, server name, a hint for the assistant |
| `tools/list` | The list of tools with descriptions and input schemas |
| `tools/call` | Call a tool: `name` and `arguments` (the API method parameters) |
| `ping` | Connectivity check |

There are no sessions and no event stream: each request stands alone, GET on the server address returns 405.

## If the assistant reports an error

A method error reaches the assistant as text with a code, for example `403 tariff_required` — posts are closed on “API.Max Test”, or `429 quota_exceeded` — the requests for the period have run out. Codes are on the [“Errors”](/en/api/errors/) page.

| What happened | What you get |
|---|---|
| An API method error (plan, no channel, limit) | `result` with `isError: true` and text like `403 tariff_required: …` |
| Unknown tool, an extra or missing argument, a value that breaks the address (`/`, `?`, `#`) | JSON-RPC error `-32602` |
| A wrong argument type or value (for example, `kind=group`) | `result` with `isError: true` and the method’s `400` error — costs as a request |
| Unknown protocol method | JSON-RPC error `-32601` |
| The body isn't JSON or not a JSON-RPC 2.0 object | JSON-RPC errors `-32700` and `-32600` |
| No key or a wrong key | HTTP 401 |