# 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 Vibecode API.
- `mcp-docs` — reference for Bitrix24 REST methods.

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

## What you can do through MCP

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

### Deal analytics

> **User:** Show the total value of deals in progress for each assigned user 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 scopes: `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 in 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 — looks up the OpenAI provider identifier.
2. `manage_ai_credentials` with the `create` action — saves the key; the key is validated with the provider before the write, and the call 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 Vibecode API. Below: 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
```

### Prepare the client environment

If the owner provides a one-time code, exchange it using [Code instead of a key](/docs/keys-auth/me#code-instead-of-a-key). If the dashboard shows the key, the owner saves it directly as `VIBE_API_KEY` in the project's private `.env`. In both cases the key belongs in that file, never in chat, launch arguments or MCP configuration. Exclude `.env` from git, ensure it is untracked and set mode `600` before writing a secret (on Windows, equivalent owner-only permissions). Do not print environment variables or enable shell tracing.

`mcp-vibe-api` reads its process environment and **does not load `.env` automatically**. The parent client must receive the variable before starting MCP. When saving manually, use the same format as the exchange: one `VIBE_API_KEY=<key>` line without quotes or spaces. In a dedicated POSIX shell, read only this variable as data without executing `.env`, then launch the client from that same shell:

```bash
set +x
unset VIBE_API_KEY
if ! VIBE_API_KEY=$(LC_ALL=C awk '
  /^VIBE_API_KEY=/ { count++; value = substr($0, 14) }
  END {
    if (count == 1 && value ~ /^[A-Za-z0-9_]+$/) print value
    else exit 1
  }
' .env) || [ -z "$VIBE_API_KEY" ]; then
  unset VIBE_API_KEY
  printf '%s\n' 'Cannot load VIBE_API_KEY from .env. Stop before starting the client.' >&2
  exit 1
fi
export VIBE_API_KEY
```

After writing or changing `.env`, update the parent process environment and fully restart the MCP client. Editing the file alone does not change a running client's environment. For a GUI client, forward only `VIBE_API_KEY` at launch or use a supported `envFile`: a separate private file containing only `VIBE_API_KEY`, with mode `600`, excluded from git and untracked. Do not use the shared project `.env` as an `envFile`.

### Register through configuration

Claude Code, project `.mcp.json`: [environment variable expansion](https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json) forwards the value from the client environment without saving a secret in the file:

```json
{
  "mcpServers": {
    "vibecode": {
      "command": "mcp-vibe-api",
      "args": ["--api-url", "https://vibecode.bitrix24.com"],
      "env": { "VIBE_API_KEY": "${VIBE_API_KEY}" }
    }
  }
}
```

Codex CLI, `~/.codex/config.toml`: the [`env_vars` list](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) permits forwarding the variable from the client environment:

```toml
[mcp_servers.vibecode]
command = "mcp-vibe-api"
args = ["--api-url", "https://vibecode.bitrix24.com"]
env_vars = ["VIBE_API_KEY"]
```

Cursor, `.cursor/mcp.json`: [the `${env:VIBE_API_KEY}` substitution](https://cursor.com/docs/mcp) reads the value from the client environment:

```json
{
  "mcpServers": {
    "vibecode": {
      "command": "mcp-vibe-api",
      "args": ["--api-url", "https://vibecode.bitrix24.com"],
      "env": { "VIBE_API_KEY": "${env:VIBE_API_KEY}" }
    }
  }
}
```

Alternatively, for a Cursor stdio server replace `env` with `"envFile": "${workspaceFolder}/.env.mcp"`. Use a separate private `.env.mcp` containing only `VIBE_API_KEY`, with mode `600`, excluded from git and untracked. The shared project `.env` must not be used as an `envFile`. Only the file reference is stored in the configuration. These examples cover Claude Code, Codex CLI and Cursor; check the environment forwarding mechanism for other clients.

### Run without a global install

In any configuration above, replace `"command": "mcp-vibe-api"` with `"command": "npx"` and prepend `"-y", "@bitrix24/mcp-vibecode-api"` to `args`. Keep the same `VIBE_API_KEY` environment forwarding; do not add the key value to the configuration.

### Launch parameters

Pass the key through the `VIBE_API_KEY` environment variable. Set the base URL with `--api-url` or `VIBE_API_URL`; for the URL, the flag takes precedence.

| Flag | Environment variable | Default | Description |
|------|----------------------|--------------|----------|
| — | `VIBE_API_KEY` | — | Vibecode API key (`vibe_api_...` or `vibe_app_...`) |
| `--api-url <url>` | `VIBE_API_URL` | Required for bitrix24.com | Vibecode API base URL; for bitrix24.com, set `https://vibecode.bitrix24.com` explicitly |
| `--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 |

After loading the private environment as described above, you can also run the server directly:

```bash
export VIBE_API_URL="https://vibecode.bitrix24.com"
mcp-vibe-api
```

### Access by key type

`mcp-vibe-api` works with two types of Vibecode keys and requests `/v1/me` on startup 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 (53)

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 (28) — 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)

These tools provide a unified CRUD interface across 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`, `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 (13)

| Tool | Actions |
|------------|----------|
| `manage_workday` | `open`, `close`, `pause`, `status`, `settings`, `schedule`, `records` — work time tracking and workday history. 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_catalog_product_image` | `list`, `get` — native catalog-product image metadata (`DETAIL_PICTURE`, `PREVIEW_PICTURE`, `MORE_PHOTO`), excluding files from other custom properties and signed/private download fields. Access to the untrusted `detailUrl` without a Bitrix24 account session is not guaranteed; fetch it server-side only after applying the platform SSRF policy. 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 on Bitrix24 Drive. Scope: `disk` |

The `download` action takes `fileId` — the Drive object identifier, a positive integer. This is the `id` field of an `upload` response, not its `fileId`. The response carries `content` with the file contents in base64, `contentType`, `size` in bytes, and `filename` when the Bitrix24 account supplied a file name. A file larger than 10 MiB is refused with `FILE_TOO_LARGE` — fetch that one from [Download file](/docs/entities/files/download) directly with the same API key. A missing file answers `ENTITY_NOT_FOUND`.

##### Universal Vibecode API call (1)

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

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

The tool reads platform JSON envelopes only, so it refuses some routes before sending the request. A route that returns bytes is `NON_JSON_RESPONSE_UNSUPPORTED`: go through `manage_file` for Drive files, and through your own HTTP client for CRM attachments, app blueprints, and storage objects. Browser entry points of the OAuth and connect flows answer with a redirect and are refused with `REDIRECT_ROUTE_UNSUPPORTED`, because following one would carry the API key to a host the platform does not choose. A full address instead of a path, and a path that leaves `/v1/`, answer `INVALID_PATH`.

#### 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 (13) — Bitrix24 account key

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

##### Infrastructure (4)

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 `runtime → stop → clean → download → install → env → platform_env → pre_start → service_user → systemd → start → hardening → healthcheck → tunnel_routing` |
| `manage_server_access` | `list_access`, `add_access`, `remove_access`, `b24_users_search` — Black Hole access lists with Bitrix24 user autocomplete |
| `get_server_activity` | Server activity feed, newest first: failed deliveries of Bitrix24 account events and of events to the bot, failed deploys and commands, wake-ups, status changes. Call it first when an application or bot does not work. It does not see API call errors, a bot that pulls events by polling, or successful deliveries |

##### 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`). Placements that could not be removed come back in `data.placements` |
| `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 optional: the platform supplies an icon itself and reports that in the `optionsDefaulted` field, and your own value always takes precedence over the supplied default |

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, misbound, 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. The base `placements` list is returned in each of these cases.

The reconciliation outcome against the Bitrix24 account is read from the `data.portalSync` field, not from the presence or the length of `handlers`: `ok` — the Bitrix24 account returned every bound code, `drift` — the Bitrix24 account did not return some of the codes and they are listed in `data.missingOnPortal`, `unknown` — the binding is not confirmed. The reason for a value other than `ok` is returned in `data.portalSyncReason`: `no_oauth_session`, `empty_vibe_list`, `b24_unreachable`, `unpublished` or `missing_on_portal`. The `unknown` value does not confirm the binding. With the `unpublished` reason (the application is withdrawn from the catalog) the Bitrix24 account is still queried, so `handlers` and the `misbound` flag are present — in the other cases `unknown` comes without `handlers`.

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 and are absent from Bitrix24 do not make it into `handlers` and produce `portalSync` equal to `drift`: the user sees the binding in Vibecode while it is in fact absent from the Bitrix24 account — for example, the registration was removed 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" } }
      }
    ],
    "portalSync": "drift",
    "portalSyncReason": "missing_on_portal",
    "missingOnPortal": ["LEFT_MENU"]
  }
}
```

In the example above `LEFT_MENU` is present in `placements` but absent from `handlers` — it is not bound in the Bitrix24 account, which is what the `portalSync` and `missingOnPortal` fields state. It is restored by re-registration via `bind`. Example without `handlers` (a call without `Bearer` or no bindings):

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

#### 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` — feedback tickets 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, capabilities. The `sections` parameter narrows the response and accepts only `portal`, `tariff`, `capabilities`, `scopes`; the infrastructure access verdict lives in `capabilities.servers.create`. `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 Vibecode 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 from the plan gate, the trial period and the balance, with `userMessage` / `alternatives` / `hint` hints |
| `vibe://error-codes` | Catalog of Vibecode API error codes and the shape of their response |

### Prompts

Ready-made multi-step prompts for the AI agent. The client activates them 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: activity feed, status, metrics, logs, recovery options |
| `upgrade-from-trial` | Explaining plan 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 \
  --api-url https://vibecode.bitrix24.com \
  --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 does 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 network access.

```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 Vibecode API directly without MCP

If an MCP client is unavailable, the agent can call the API over HTTP. Preparation depends on what the owner provides:

- **Code.** Give the agent the code and the self-description URL. The agent [exchanges the code and privately saves the key](/docs/keys-auth/me#code-instead-of-a-key).
- **Key from the dashboard.** The owner saves the key as `VIBE_API_KEY` in the project's private `.env` with mode `600`, excluded from git and untracked. Never paste the key into chat or MCP configuration. The agent receives it from the local environment.

For the code path, use this template without a usable code:

```text
My code for the VibeCode platform: VIBE-… (swap for a key)

Documentation: https://vibecode.bitrix24.com/v1/me

Describe your task...
```

In both cases direct API requests use the local `VIBE_API_KEY` without revealing it in chat. Load the variable as described in [Prepare the client environment](#prepare-the-client-environment). If the agent lacks HTTP access or access to a private file, ask the owner to exchange the code manually using the guide or save the dashboard key in `.env` with the same access restrictions.

## Security

- Pass the API key through the `VIBE_API_KEY` environment variable; store only its name or substitution in the configuration. Keep the private `.env` mode `600`, excluded from git and untracked. Never print the key in chat or logs. Always pair it with the `VIBE_API_URL` or `--api-url` value for the Vibecode instance that issued the key.
- 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.
- For 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

- [Keys and authorization](/docs/keys-auth)
- [Entity API](/docs/entity-api)
- [AI Router](/docs/ai)
- [Feedback](/docs/feedback)