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 | Tools (53) | HTTP transport | mcp-docs | 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 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).

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:

claude mcp add vibecode -- mcp-vibe-api --key vibe_api_your_key_here --api-url https://vibecode.bitrix24.com

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:

codex mcp add vibecode -- mcp-vibe-api --key vibe_api_your_key_here --api-url https://vibecode.bitrix24.com

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

Gemini CLI:

gemini mcp add vibecode mcp-vibe-api --key vibe_api_your_key_here --api-url https://vibecode.bitrix24.com

The entry goes into ~/.gemini/settings.json. To pass the key via environment variables: gemini mcp add -e VIBE_API_KEY=vibe_api_your_key_here -e VIBE_API_URL=https://vibecode.bitrix24.com 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):

{
  "mcpServers": {
    "vibecode": {
      "command": "mcp-vibe-api",
      "args": ["--key", "vibe_api_your_key_here", "--api-url", "https://vibecode.bitrix24.com"]
    }
  }
}

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

{
  "mcpServers": {
    "vibecode": {
      "command": "mcp-vibe-api",
      "args": ["--key", "vibe_api_your_key_here", "--api-url", "https://vibecode.bitrix24.com"]
    }
  }
}

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

[mcp_servers.vibecode]
command = "mcp-vibe-api"
args = ["--key", "vibe_api_your_key_here", "--api-url", "https://vibecode.bitrix24.com"]

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:

{
  "mcpServers": {
    "vibecode": {
      "command": "npx",
      "args": ["-y", "@bitrix24/mcp-vibecode-api", "--key", "vibe_api_your_key_here", "--api-url", "https://vibecode.bitrix24.com"]
    }
  }
}

Launch parameters

The key and base URL are passed via command-line flags or environment variables. If there is a conflict, the flag wins.

Set the key via an environment variable to avoid storing it in configs:

export VIBE_API_KEY="vibe_api_your_key_here"
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.

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.

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)

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.

CRM extensions and working with the Bitrix24 account (13)

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 directly with the same API key. A missing file answers ENTITY_NOT_FOUND.

Universal Vibecode API call (1)

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.

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.

Applications (5)

Publishing applications (3)

Placements (1)

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):

{
  "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):

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

Service (2) — any key

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

Resources

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

Prompts

Ready-made multi-step prompts for the AI agent. The client activates them by name.

HTTP transport

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

mcp-vibe-api \
  --key vibe_api_your_key_here \
  --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

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 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.

npm install -g @bitrix24/mcp-docs

Registration in a client

Via CLI:

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:

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

Tools (8)

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, 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, or public configs. 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 and create a new one.

See also

• Keys and authorization
• Entity API
• AI Router
• Feedback