# MCP for AI

Vibecode publishes two MCP servers for AI agents — suitable for Claude Desktop, Claude Code, Cursor, Codex CLI, Windsurf, Gemini CLI and any other client that supports the Model Context Protocol.

- `mcp-vibe-api` — tools for working with Bitrix24 through the Vibe API.
- `mcp-docs` — reference for Bitrix24 REST methods.

[Install mcp-vibe-api](#mcp-vibe-api) | [Tools (51)](#tools-51) | [HTTP transport](#http-transport) | [mcp-docs](#mcp-docs) | [Security](#security)

## What you can do through MCP

A selection of dialogs with an AI agent and the tools the agent actually calls. Helps you assess the capabilities of `mcp-vibe-api` and pick the set of scopes for a key.

### Deal analytics

> **User:** Show the total of deals in progress for each owner over the last month.

The agent calls in sequence:
1. `aggregate_entities` for the `deals` entity with a filter on `closeDate`, a `sum` aggregate on the `amount` field and grouping by `assignedById`.
2. `list_entities` for the `users` entity — to replace identifiers with employee names.

Key scope: `crm`, `user`.

### Creating and publishing a bot

> **User:** Register a bot named "Assistant" and send a test message to the chat with my colleague.

The agent calls in sequence:
1. `manage_bot` with the `register` action — creates a bot on the Bitrix24 account.
2. `manage_bot` with the `get_events` action — gets the identifier of the dialog with the colleague from an incoming event.
3. `manage_bot_messages` with the `send` action — sends a welcome message to the right dialog.

Key scope: `imbot`.

### Deploying an application to a server

> **User:** Spin up a new server in Bitrix24 Cloud and roll out the application archive there.

The agent calls in sequence:
1. `manage_server` with the `list_providers`, `list_plans`, `list_regions`, `list_images` actions — assembles the catalog.
2. `manage_server` with the `create` action — creates a server in the chosen configuration.
3. `manage_server` with the `get` action — waits until the status becomes `RUNNING` and `CONNECTED`.
4. `manage_server_deploy` with the `deploy` action — runs the deployment pipeline (archive upload, install, systemd, health check).
5. `manage_server_deploy` with the `logs` action — reads the logs on errors.

Key scope: `vibe:infra`.

### Connecting your own AI provider

> **User:** Add my OpenAI key and make a test request to gpt-4o.

The agent calls in sequence:
1. `manage_ai_credentials` with the `list_providers` action — finds out the OpenAI provider identifier.
2. `manage_ai_credentials` with the `create` action — saves the key; the provider is validated before the write and returns `422 CREDENTIAL_INVALID` if the key does not work.
3. `ai_chat` with the `chat` action and the `model: "openai/gpt-4o"` parameter — sends a test request through the AI Router.

Key scope: `vibe:ai`.

### Submitting a support request through AI

> **User:** The `/v1/deals/aggregate` endpoint sometimes returns an empty response — open a ticket with the details.

The agent calls in sequence:
1. `get_me` — fetches the Bitrix24 account identifier and the current plan for the `context` field.
2. `manage_feedback` with the `create` action — submits a ticket with category `BUG`, a title, a reproduction description and a serialized `context` (endpoint, request body, response code).

Key scope: ticket creation is available to any key.

## mcp-vibe-api

A server that gives an AI agent access to Bitrix24 through the Vibe API. Next — installation, launch parameters, tools, Resources, Prompts and HTTP transport.

### Installation

The [`@bitrix24/mcp-vibecode-api`](https://www.npmjs.com/package/@bitrix24/mcp-vibecode-api) package. After installation the `mcp-vibe-api` command becomes available. Requires Node.js version 18 or higher — any current LTS build works (18, 20, 22).

```bash
npm install -g @bitrix24/mcp-vibecode-api
```

### Registration in a client via CLI

If the client can manage MCP servers from the console, there is no need to edit a config file — a single command is enough.

Claude Code:

```bash
claude mcp add vibecode -- mcp-vibe-api --key vibe_api_your_key_here
```

The command adds the server to the current user's local config. To share the setup across the whole project, add the `-s project` flag — the config goes into the repository's `.mcp.json`. Manage the list: `claude mcp list`, `claude mcp remove vibecode`.

Codex CLI:

```bash
codex mcp add vibecode -- mcp-vibe-api --key vibe_api_your_key_here
```

The entry goes into `~/.codex/config.toml`. To pass the API key via an environment variable instead of an argument: `codex mcp add vibecode --env VIBE_API_KEY=vibe_api_your_key_here -- mcp-vibe-api`. For project scope, create `.codex/config.toml` in the repository root and write the `[mcp_servers.vibecode]` block directly.

Gemini CLI:

```bash
gemini mcp add vibecode mcp-vibe-api --key vibe_api_your_key_here
```

The entry goes into `~/.gemini/settings.json`. To pass the key via an environment variable: `gemini mcp add -e VIBE_API_KEY=vibe_api_your_key_here vibecode mcp-vibe-api`. For project scope use `.gemini/settings.json` in the repository root.

### Registration via a config file

Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "vibecode": {
      "command": "mcp-vibe-api",
      "args": ["--key", "vibe_api_your_key_here"]
    }
  }
}
```

Cursor (`.cursor/mcp.json` in the project root):

```json
{
  "mcpServers": {
    "vibecode": {
      "command": "mcp-vibe-api",
      "args": ["--key", "vibe_api_your_key_here"]
    }
  }
}
```

Codex CLI (`~/.codex/config.toml`):

```toml
[mcp_servers.vibecode]
command = "mcp-vibe-api"
args = ["--key", "vibe_api_your_key_here"]
```

### Running without a global install

If you cannot install the package globally, replace `mcp-vibe-api` with `npx -y @bitrix24/mcp-vibecode-api` in any config above. Example for Claude Desktop:

```json
{
  "mcpServers": {
    "vibecode": {
      "command": "npx",
      "args": ["-y", "@bitrix24/mcp-vibecode-api", "--key", "vibe_api_your_key_here"]
    }
  }
}
```

### Launch parameters

The key and base URL are passed via command-line flags or environment variables. On a collision the flag wins.

| Flag | Environment variable | Default | Description |
|------|----------------------|--------------|----------|
| `--key <api-key>` | `VIBE_API_KEY` | — | Vibecode API key (`vibe_api_...` or `vibe_app_...`) |
| `--api-url <url>` | `VIBE_API_URL` | `https://vibecode.bitrix24.com` | Vibe API base URL |
| `--http` | — | disabled | Enable HTTP transport instead of stdio |
| `--http-token <token>` | `VIBE_MCP_HTTP_TOKEN` | — | Bearer token for HTTP transport (required with `--http`) |
| `--host <host>` | — | `127.0.0.1` | Address for HTTP transport |
| `--port <port>` | — | `3001` | TCP port for HTTP transport |
| `--allowed-origins <csv>` | — | empty | Comma-separated list of allowed browser `Origin` values |
| `--max-body-kb <n>` | — | `256` | Request body limit in kilobytes |
| `--rate-limit <rpm>` | — | `300` | Request limit per minute per IP |
| `-h`, `--help` | — | — | Show help |
| `-v`, `--version` | — | — | Show package version |

Setting the key via an environment variable, so as not to store it in configs:

```bash
export VIBE_API_KEY="vibe_api_your_key_here"
mcp-vibe-api
```

### Access by key type

`mcp-vibe-api` works with two types of Vibecode keys and on startup requests `/v1/me` to determine the type. After that the client is given only the tools the key can use.

| Key type | Which tools are available |
|-----------|----------------------------|
| `vibe_api_...` or `vibe_app_...` (Bitrix24 account key) | Bitrix24 data, AI, app building, service |
| `vibe_live_...` (management key) | Platform management, service |

Each tool group below states the key type that fits it.

### Tools (51)

All tools return JSON. For specialized endpoints there are typed wrappers — use them instead of `call_api` when available: parameter hints and validation are better. The tools are grouped into five clusters by task type.

#### Bitrix24 data (27) — Bitrix24 account key

Reading and writing Bitrix24 account data: CRM entities, chats and bots, CRM extensions, telephony, files, workflows, work time. Suits most AI-agent tasks.

##### Entities of CRM and other modules (10)

Cover a unified CRUD interface over 40+ Bitrix24 entities — from deals and contacts to tasks, files, documents and smart-process records.

| Tool | Description |
|------------|----------|
| `discover` | List of entities and their fields from the OpenAPI schema |
| `get_fields` | Entity fields including custom `UF_*` fields |
| `list_entities` | List of records with filtering, sorting, auto-pagination when `limit > 50` |
| `get_entity` | Record by ID |
| `create_entity` | Create a record |
| `update_entity` | Partial update of a record |
| `delete_entity` | Delete a record |
| `search_entities` | Search with the `$gt`, `$gte`, `$lt`, `$lte`, `$ne`, `$contains`, `$in`, `$nin` operators |
| `batch_entities` | Bulk create, update and delete of up to 500 records per call |
| `aggregate_entities` | Aggregation: `count`, `sum`, `avg`, `min`, `max` with grouping via `groupBy` |

Supported entities: `deals`, `contacts`, `companies`, `leads`, `quotes`, `activities`, `products`, `product-sections`, `statuses`, `currencies`, `deal-categories`, `requisites`, `timelines`, `invoices`, `items`, `smart-processes`, `tasks`, `calendar-events`, `files`, `folders`, `storages`, `users`, `departments`, `workgroups`, `chats`, `list-elements`, `catalog-products`, `catalog-sections`, `catalog-prices`, `orders`, `order-statuses`, `basket-items`, `payments`, `sites`, `pages`, `doc-templates`, `documents`, `bookings`, `bizproc-templates`, `openline-configs`, `telephony-lines` and others.

##### Chats (1)

| Tool | Actions |
|------------|----------|
| `manage_chat` | `list_recent`, `find`, `get`, `send_message`, `read_messages`, `create`, `add_users`, `bulk_messages` |

Scope: `im`. Manages chats and messages on the user's side; for chats owned by a bot use `manage_bot_chat`.

##### Bots (3)

Managing bots on the Bitrix24 platform — registration, chats, messaging. Key scope: `imbot`.

| Tool | Actions |
|------------|----------|
| `manage_bot` | `register`, `unregister`, `update`, `list`, `get`, `get_events` |
| `manage_bot_chat` | `create`, `get`, `update`, `leave`, `add_user`, `remove_user`, `set_owner` |
| `manage_bot_messages` | `send`, `edit`, `delete`, `add_reaction`, `remove_reaction`, `read`, `get_history`, `send_typing` |

##### CRM extensions and working with the Bitrix24 account (12)

| Tool | Actions |
|------------|----------|
| `manage_workday` | `open`, `close`, `pause`, `status`, `settings`, `schedule` — work time tracking. Scope: `timeman` |
| `manage_workflow` | `start`, `list`, `terminate`, `send_event` — workflows. Scope: `bizproc` |
| `send_notification` | Push notification to a Bitrix24 user. Scope: `im` |
| `manage_call` | `register`, `finish`, `auto_call`, `callback`, `statistics`, `voices` — telephony and auto-dialing with TTS. Scope: `telephony` |
| `manage_trigger` | `fire`, `list` — CRM automation triggers. Scope: `bizproc` |
| `manage_timeline_log` | `create`, `list`, `get`, `delete`, `add_note`, `get_note`, `delete_note`, `pin`, `unpin`, `bind`, `unbind`, `get_bindings` — entries in the timeline of CRM entities. Scope: `crm` |
| `manage_warehouse` | `list`, `get`, `create`, `delete`, `get_stock` — warehouses and stock. Scope: `catalog` |
| `manage_post` | `list`, `create`, `update`, `delete`, `share`, `add_comment` — posts in the Feed. Scope: `log` |
| `manage_userfield` | `list`, `get`, `types`, `create`, `update`, `delete` — custom fields in fixed CRM entities and smart processes. Scope: `crm` |
| `manage_task_time` | `list`, `get`, `add`, `update`, `delete` — time tracking for tasks. Scope: `task` |
| `crm_extras` | `stage_history`, `find_duplicates` — stage history and duplicate search. Scope: `crm` |
| `manage_file` | `upload`, `download` — uploading and downloading files in Bitrix24.Disk. Scope: `disk` |

##### Universal Vibe API call (1)

| Tool | Description |
|------------|----------|
| `call_api` | Arbitrary HTTP call to the Vibe API: `method`, `path`, `body`, `query`. A fallback channel for endpoints without a typed wrapper |

Example call: `call_api({ method: "GET", path: "/v1/calls/statistics" })`.

#### AI (2) — Bitrix24 account key

Connecting AI models through the AI Router and managing BYOK credentials. Scope: `vibe:ai`.

| Tool | Actions |
|------------|----------|
| `ai_chat` | `list_models`, `chat` — OpenAI-compatible chat completions through `/v1/chat/completions`; the default model is the free `bitrix/bitrixgpt-5.5` |
| `manage_ai_credentials` | `list`, `create`, `update`, `delete`, `test`, `usage`, `list_providers` — managing BYOK credentials for connecting third-party AI providers. Create and update validate the key before saving and return `422 CREDENTIAL_INVALID` on error |

#### App building (12) — Bitrix24 account key

Creating Bitrix24 applications, deploying the server side on cloud VMs, configuring placements in the Bitrix24 account interface.

##### Infrastructure (3)

Cloud servers for applications and Black Hole tunnels. Scope: `vibe:infra`.

| Tool | Actions |
|------------|----------|
| `manage_server` | Catalog: `list_providers`, `list_plans`, `list_regions`, `list_images`. Lifecycle: `create`, `list`, `get`, `delete`, `get_ssh`. State: `start`, `stop`, `reboot`, `wake`, `sleep_now`, `refresh`. Operations: `metrics`, `set_port`, `set_sleep`, `set_mode`, `repair`, `repair_status` |
| `manage_server_deploy` | `deploy`, `exec`, `upload`, `logs`, `clear_lock` — deployment pipeline with the steps `stop → clean → download → runtime → install → env → pre_start → service_user → systemd → start → healthcheck → tunnel_routing` |
| `manage_server_access` | `list_access`, `add_access`, `remove_access`, `b24_users_search` — Black Hole access lists with Bitrix24 user autocomplete |

##### Applications (5)

| Tool | Description |
|------------|----------|
| `list_apps` | List of applications, optional filter by status |
| `get_app` | Application by ID |
| `create_app` | Create an application |
| `update_app` | Update an application |
| `delete_app` | Delete an application |

##### Publishing applications (3)

| Tool | Description |
|------------|----------|
| `publish_app` | Publish an application for the whole Bitrix24 account |
| `unpublish_app` | Unpublish an application (status `UNPUBLISHED`) |
| `deploy_app` | Publish an application to the Bitrix24 account catalog (target `PORTAL`). For source-code deployment to a server, use `manage_server_deploy` |

##### Placements (1)

| Tool | Actions |
|------------|----------|
| `manage_placements` | `list_bound`, `list_available`, `bind`, `unbind` — embedding an application into the Bitrix24 interface, with the full description of the operations in [Placements](/docs/apps/placements). For IM placements (`IM_SIDEBAR`, `IM_NAVIGATION`, `IM_TEXTAREA`) the `options.iconName` parameter is required — it is validated on the client side before the request is sent |

Scope: `placement`.

The `list_bound` action (under the hood — `GET /v1/placements`) returns the list of placement codes bound in Vibecode and — when a session token is present (`Authorization: Bearer`) — an additional `handlers` field. This is an array with the actual handler URL from Bitrix24 for each code: `{ placement, handler, title?, options?, langAll? }`. Type: `Array<{...}> | undefined` — the field is absent if the request came without `Bearer`, the application has no bound placements, or the Bitrix24 response could not be obtained (in which case the base `placements` list is still returned — graceful degrade).

The `handlers` field is built as the intersection of our `App.placements` with the response of the Bitrix24 `placement.get` method. Codes that exist in our database but are absent in Bitrix24 do not make it into `handlers` — this is a drift signal, useful for diagnostics: the user sees the binding in Vibecode, but it is in fact absent on the Bitrix24 account (for example, someone removed it through the Bitrix24 interface). The base `data.placements` list stays the same — there are no breaking changes to the response shape.

Example (with `handlers`):

```json
{
  "success": true,
  "data": {
    "placements": ["CRM_DEAL_DETAIL_TAB", "LEFT_MENU"],
    "appId": "5b5c7e6f-…",
    "appTitle": "My App",
    "handlers": [
      {
        "placement": "CRM_DEAL_DETAIL_TAB",
        "handler": "https://myapp.example.com/deal-tab",
        "title": "My tab",
        "options": {},
        "langAll": { "en": { "TITLE": "My tab" } }
      }
    ]
  }
}
```

In the example above `LEFT_MENU` is present in `placements` but absent in `handlers` — it is not bound on the Bitrix24 account, re-registration via `bind` is needed. Example without `handlers` (a call without `Bearer` or no bindings):

```json
{
  "success": true,
  "data": {
    "placements": [],
    "appId": "5b5c7e6f-…",
    "appTitle": "My App"
  }
}
```

#### Platform management (8) — management key

This group is available only to Vibecode management keys (format `vibe_live_...`).

| Tool | Description |
|------------|----------|
| `list_portals` | List of Bitrix24 accounts available with the management key |
| `list_keys` | List of Bitrix24 account API keys |
| `get_key` | Key by ID |
| `create_key` | Create a key with scopes, an IP allowlist and an expiration |
| `update_key` | Modify a key |
| `delete_key` | Delete a key |
| `rotate_key` | Rotate the key secret |
| `manage_feedback` | `create`, `list`, `get`, `update`, `comment` — requests through `/v1/feedback`. A management key works with all Bitrix24 accounts; for a Bitrix24 account key this is creating and reading its own tickets, and with the additional `vibe:feedback` scope — also updating and commenting |

#### Service (2) — any key

Available to both a Bitrix24 account key and a management key.

| Tool | Description |
|------------|----------|
| `get_me` | Snapshot of the current key: owner, Bitrix24 account, plan, trial state, capabilities. The `sections` parameter narrows the response; `refresh: 'tariff'` forces a re-check of the plan through Bitrix24 |
| `check_for_updates` | Check for `mcp-vibe-api` updates in the npm registry. Returns the current and latest versions and the update command |

### Resources

URIs of the form `vibe://...` serve reference materials for the AI agent.

| URI | Description |
|-----|----------|
| `vibe://api-reference` | Full Vibe API reference in Markdown format |
| `vibe://entity/{plural}` | Reference for a specific entity — for example `vibe://entity/deals`, `vibe://entity/tasks` |
| `vibe://tariff-gate` | Map of 402 errors of the tariff gate, the trial period and the balance with `userMessage` / `alternatives` / `hint` hints |
| `vibe://error-codes` | Catalog of Vibe API error codes and the shape of their response |

### Prompts

Ready-made multi-step prompts for the AI agent. Activated by the client by name.

| Name | Description |
|-----|----------|
| `create-bitrix24-app` | Scenario for creating, publishing and deploying a Bitrix24 application |
| `deploy-app-step-by-step` | Deploying an application to a server: wake, upload, command execution, health check |
| `diagnose-server-issue` | Diagnosing server problems: status, metrics, logs, recovery options |
| `upgrade-from-trial` | Explaining tariff-gate blocks and the path to a commercial plan |

### HTTP transport

Besides stdio (used by default) `mcp-vibe-api` supports HTTP transport. Suitable for server-side integrations where stdio is inconvenient.

```bash
mcp-vibe-api \
  --key vibe_api_your_key_here \
  --http \
  --http-token "$(openssl rand -hex 32)" \
  --allowed-origins https://your-client.example.com
```

The client sends `POST http://127.0.0.1:3001/mcp` with the headers:

```
Authorization: Bearer <token>
Content-Type: application/json
```

| Response code | Reason |
|------------|---------|
| `401` | Missing or invalid Bearer token |
| `403` | The `Host` header did not match, the `Origin` is not in the allowlist, or an `OPTIONS` without an allowed `Origin` |
| `404` | The path differs from `/mcp` |
| `405` | The request method differs from `POST` or `OPTIONS` |
| `413` | The request body exceeds `--max-body-kb` |
| `415` | The `Content-Type` differs from `application/json` |
| `429` | The per-minute request limit is exceeded, the response contains `Retry-After: 60` |

The server refuses to start if `--http` is given without a token. The tokens themselves are not written to logs — on startup only their source is stated (a flag or an environment variable).

## mcp-docs

A reference for the Bitrix24 REST API: methods, scopes, placements, application types and categories. Works offline without an API key — all data is embedded in the package.

### Installation

The [`@bitrix24/mcp-docs`](https://www.npmjs.com/package/@bitrix24/mcp-docs) package. After installation the `mcp-docs` command becomes available. No API key is needed — the reference is embedded in the package and works without a network.

```bash
npm install -g @bitrix24/mcp-docs
```

### Registration in a client

Via CLI:

```bash
claude mcp add bitrix24-docs -- mcp-docs
codex mcp add bitrix24-docs -- mcp-docs
gemini mcp add bitrix24-docs mcp-docs
```

Via a config file:

```json
{
  "mcpServers": {
    "bitrix24-docs": {
      "command": "mcp-docs"
    }
  }
}
```

### Tools (8)

| Tool | Description |
|------------|----------|
| `search_docs` | Full-text search of the reference |
| `get_rest_methods` | List of REST methods with a filter by scope or search query |
| `get_method_detail` | Detailed description of a method: parameters, response, examples |
| `get_scopes` | List of scopes with descriptions |
| `get_placements` | List of UI placements with a filter by module |
| `get_placement_detail` | Detailed description of a placement |
| `get_app_types` | Bitrix24 application types |
| `get_categories` | Bitrix24 application categories |

Additionally the server publishes a resource with the REST API guide and a `bitrix24-rest-intro` prompt — an introduction to REST and to the Vibecode proxy syntax.

## Using the Vibe API directly without MCP

If an MCP client is unavailable, give the AI model an API key and a link to the full reference:

```
Here is my Vibecode API key: vibe_api_your_key_here
Full documentation: https://vibecode.bitrix24.com/llms-full.txt

Describe your task...
```

`mcp-vibe-api` connects to any client that supports the Model Context Protocol — Claude Desktop, Claude Code, Cursor, Codex CLI, Windsurf, Gemini CLI and others. A direct key without MCP works even for clients without protocol support, for example ChatGPT.

## Security

- Pass the API key via the `VIBE_API_KEY` environment variable or the `--key` flag — do not write the key into scripts, repositories and public configs.
- Create a separate key for each AI agent and leave only the scopes you need — `vibe_api_...` keys support a scope list and an expiration.
- For server-side scenarios configure an IP allowlist and a fixed key lifetime.
- In HTTP transport use a Bearer token from `--http-token` or `VIBE_MCP_HTTP_TOKEN` and keep `--host 127.0.0.1` if external access is not needed.
- If a key is compromised — revoke it in the [API Keys section](https://vibecode.bitrix24.com/keys) and create a new one.

## See also

- [Key management](/docs/keys-auth) — Vibecode key types and their scopes
- [Vibe API endpoints](/docs/entity-api) — unified CRUD over Bitrix24 entities
- [AI Router](/docs/ai) — models and BYOK providers
- [Feedback](/docs/feedback) — submitting problem reports through `/v1/feedback`