# Connector gateway (MCP)

The gateway through which the Cowork desktop calls the tools of services connected to the Bitrix24 account. It speaks MCP
Streamable HTTP without sessions.

**Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** Cowork desktop key

## Who can call it

Only the key the Cowork desktop receives at sign-in. Any other key gets `403 CONNECTOR_KEY_NOT_ALLOWED`.

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`, `ping`, `tools/list`, `tools/call`. With the feature on, `GET` and `DELETE` answer `405`.

```bash
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"}'
```

## Error codes

| HTTP | Code | When |
|---|---|---|
| 400 | JSON-RPC `-32600` | the request carries a batch: the gateway accepts one message |
| 401 | `MISSING_API_KEY`, `INVALID_API_KEY`, `KEY_INACTIVE`, `KEY_EXPIRED` | the key is missing, unknown, inactive or expired |
| 403 | `CONNECTOR_KEY_NOT_ALLOWED` | the key is not a Cowork desktop key |
| 403 | `OWNER_BLOCKED` | the key owner is no longer active on the portal |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | the key is in read-only mode |
| 404 | `ROUTE_NOT_FOUND` | the feature is not enabled for the portal or the user |
| 405 | `METHOD_NOT_ALLOWED` | the method is not `POST` |
| 413 | `PAYLOAD_TOO_LARGE` | the request body is larger than 256 KiB |
| 429 | `RATE_LIMITED` | the platform-wide cap of 300 requests per minute for one key was exceeded; each key has its own counter. The effective limit for your key is returned in the `x-ratelimit-limit` header (the cap is divided across replicas) |
| 503 | `CONNECTOR_VAULT_NOT_CONFIGURED` | connectors are not configured on this server |

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