#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 | Tools (51) | HTTP transport | mcp-docs | 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 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

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

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:

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

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

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

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

Codex CLI (~/.codex/config.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:

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

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

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.

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.

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)

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 (12)

#Universal Vibe API call (1)

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.

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

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

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

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

#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. Activated by the client 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 \
  --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 a network.

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 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 and create a new one.

#See also

• Key management — Vibecode key types and their scopes
• Vibe API endpoints — unified CRUD over Bitrix24 entities
• AI Router — models and BYOK providers
• Feedback — submitting problem reports through /v1/feedback