Connector gateway (MCP)

The gateway lets Cowork and linked Vibe applications call tools of services connected to the Bitrix24 account. It speaks MCP Streamable HTTP without sessions.

Base URL: https://vibecode.bitrix24.com/v1 | Authorization: Cowork device key or eligible application key

Who can call it

Cowork accepts device keys with purpose cowork-desktop. Applications require explicit effective vibe:connectors and an active application with its personal application key or OAuth application key. Its owner and Bitrix24 account must match the key. While the feature is not enabled for the account, routes return 404 ROUTE_NOT_FOUND. When it is enabled, other keys receive 403 CONNECTOR_KEY_NOT_ALLOWED.

The principal is the key owner, not a browser viewer or an identity supplied in headers. Applications see only shared PORTAL connections allowed by administrator rules and owner permissions. The scope creates neither connections nor rules. The exact application allowlist is GET /v1/connectors, POST /v1/connectors/mcp, GET /v1/connectors/write-tickets/{id} and GET /v1/me; all other host routes and operations, including access requests and connection management, are denied.

Eligible applications discover data.connectorHost from GET /v1/me: host = VIBE_APP, applicationId, connectionScope = PORTAL, mcpUrl = /v1/connectors/mcp and confirmationMode = web_owner. Absence of this block grants no access. Admission and permissions are checked again on each request.

While the feature is off, the path answers 404 ROUTE_NOT_FOUND to any request, before the key, the method and the body are checked. If the feature is on only for some Bitrix24 accounts or users, a key outside that group gets the same 404 right after the key check.

Request

POST /v1/connectors/mcp

POST /v1/connectors/mcp accepts a single JSON-RPC 2.0 message up to 256 KiB; a batch of messages is rejected. Methods: initialize, notifications/initialized, ping, tools/list, tools/call. With the feature on, Cowork GET and DELETE answer 405; applications receive 403 CONNECTOR_KEY_NOT_ALLOWED.

curl https://vibecode.bitrix24.com/v1/connectors/mcp \
  -H "Authorization: Bearer YOUR_COWORK_DESKTOP_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tools, payment and write approval

The meta-tools are connectors_available, connectors_find_tools and connectors_run_tool; individual tools use the exposed slug__tool name. Unavailable tools return UNKNOWN_TOOL. Use connectors_get_result to retrieve an accepted BRIDGE operation.

Successful paid calls charge the current Bitrix24 account, with the key owner in the ledger and the application/key in the call journal. They keep the existing soft daily cap with UTC day boundaries. Free calls and refusals have no charge. ACCOUNT_FROZEN, INSUFFICIENT_BALANCE, DAILY_CAP_REACHED and COMPANY_BUDGET_EXHAUSTED refuse execution before the vendor call.

WRITE requires administrator READ_WRITE, a writable key and writes enabled for the Bitrix24 account. Applications require owner approval in the web account and no desktop version header. The minimum desktop version (including an empty minimum that disables writing) applies only to Cowork. The host reads its own pending ticket through the host API, waits for human approval, then repeats the same tool arguments with the same key. Approval is consumed once. A paid refusal before execution does not consume an already approved ticket. Sensitive arguments and vendor secrets do not appear in the confirmation card or administrative journal.

Error codes

Tool errors come back in the tools/call result with isError: true and the code in _meta["vibe/error"].code.

BRIDGE operations

Every BRIDGE start, including a call through connectors_run_tool, requires a UUID in params._meta["vibe/idempotencyKey"]. Keep it outside tool arguments. Retry the same action with the same UUID, arguments and key after a timeout or lost response. Generate a different UUID for a new action. Reusing a UUID for different input yields CONNECTOR_OPERATION_CONFLICT and must not be automatically retried.

Quick READ

The synthetic bridge_test tools illustrate the contract. Use the name and input schema returned by discovery for your connector. A quick READ returns its final tool result immediately:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"bridge_test__quick_read","arguments":{},"_meta":{"vibe/idempotencyKey":"123e4567-e89b-42d3-a456-426614174000"}}}

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"ok\":true}"}]}}

Pending and result retrieval

A slow call returns pending, without isError. It is neither a vendor error nor terminal success. Use connectors_get_result through tools/call on the same POST /v1/connectors/mcp endpoint; there is no separate V1 result URL:

{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"The operation is in progress. Retrieve its result later by operationId through connectors_get_result."}],"_meta":{"vibe/operation":{"id":"123e4567-e89b-42d3-a456-426614174000","status":"running","retryAfterMs":1000,"expiresAt":"2026-10-12T13:00:00.000Z","resultTool":"connectors_get_result"}}}}

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"connectors_get_result","arguments":{"operationId":"123e4567-e89b-42d3-a456-426614174000"}}}

Respect retryAfterMs and wait at least one second between polls. Retrieval returns pending again or the final tool result. Closing a browser, disconnecting or reaching an HTTP timeout stops waiting, not the accepted job. Do not start a new action just to retrieve an earlier result.

Paid WRITE

Send a WRITE using a new UUID:

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"bridge_test__approved_write","arguments":{},"_meta":{"vibe/idempotencyKey":"123e4567-e89b-42d3-a456-426614174001"}}}

If approval is required, read the ticket via GET /v1/connectors/write-tickets/{id}, wait for the owner to approve it in the web account, then repeat the same tool call with the same UUID and arguments. A JSON-RPC request id may change; the idempotency UUID must not. Existing operation replay happens before new paid admission or a new WRITE gate. Approval consumption and operation reservation happen atomically; an admission failure does not spend approval or start work. A lost start response can therefore be retried without an extra effect or charge.

Ownership, lifetime and payment

Result access requires the same host, key, Bitrix24 account, connection and authorization generation, plus current permissions. Sharing an owner does not grant another application or key access. Reconnecting or revoking access hides the old payload and prevents a new start under the old authorization. Service recovery can still settle already accepted work: a valid successful paid result is charged once even if its payload is no longer visible. Retrieval and replay do not create another charge.

The price is fixed when the operation is reserved. Successful completion is attributed to the UTC day of completion under the soft daily cap; concurrent accepted jobs can exceed that cap. Pending appears as In progress in the call journal, with no paid amount until terminal settlement. The journal keeps the original call time and host/application attribution when completion arrives. Expired payloads cannot be recovered by submitting a new UUID; retained tombstones prevent repeating the old operation.

Operation errors

Tool refusals use HTTP 200 with isError: true and _meta["vibe/error"].code. CONNECTOR_OPERATION_CONFLICT is a non-retryable conflict (HTTP representation 409); CONNECTOR_OPERATION_NOT_FOUND is a neutral, non-retryable refusal (HTTP representation 404), including results unavailable to this caller. Missing or invalid idempotency metadata yields INVALID_ARGUMENTS. Admission limits yield BUSY; transport deadlines yield VENDOR_UNAVAILABLE; neither proves that accepted external work was cancelled. Do not turn uncertainty into a new WRITE. Existing authentication, unavailable-tool and paid-refusal codes remain applicable.