# MCP

> Connect Claude Code, Codex, Cursor or VS Code to the Browlix MCP server and use every API operation as a tool.

The Browlix MCP server exposes the API v1 catalog as tools, with the same permissions, limits, idempotency and audit as HTTP.

- Endpoint: `https://browlix.com/api/public/mcp`
- Transport: Streamable HTTP, stateless — every `POST` carries the API key, so reconnecting is just the next request.
- Protocol revisions (newest first):

- `2026-07-28` — modern (per-request metadata, `server/discover`, no handshake)
- `2025-11-25`, `2025-06-18`, `2025-03-26` — legacy (`initialize` handshake)

A client that speaks `2026-07-28` sends the revision and its capabilities with every request (`MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name` headers mirror the body) and may call `server/discover` first; there is no handshake. A client on an older revision starts with `initialize` and gets its own revision back when it is listed, otherwise the newest legacy one. An unknown revision is refused with error `-32022` and the supported list.

## Connect a client

Put the key in an environment variable or the client's secret prompt — never in a config file.

```bash tab="Claude Code"
export BROWLIX_API_KEY="bxk_…"
claude mcp add --transport http --scope user browlix https://browlix.com/api/public/mcp \
  --header 'Authorization: Bearer ${BROWLIX_API_KEY}'
```

```bash tab="Codex CLI"
export BROWLIX_API_KEY="bxk_…"
codex mcp add browlix --url https://browlix.com/api/public/mcp --bearer-token-env-var BROWLIX_API_KEY
```

```json tab=Cursor
{
  "mcpServers": {
    "browlix": {
      "url": "https://browlix.com/api/public/mcp",
      "headers": { "Authorization": "Bearer ${env:BROWLIX_API_KEY}" }
    }
  }
}
```

```json tab="VS Code"
{
  "inputs": [{ "type": "promptString", "id": "browlix-api-key", "description": "Browlix API key", "password": true }],
  "servers": {
    "browlix": {
      "type": "http",
      "url": "https://browlix.com/api/public/mcp",
      "headers": { "Authorization": "Bearer ${input:browlix-api-key}" }
    }
  }
}
```

Cursor reads `~/.cursor/mcp.json`; VS Code reads `.vscode/mcp.json` in the workspace. The web app shows the same snippets under **Settings → API keys**.

## Tools

- One tool per operation, named after its id with underscores: `sessions.start` → `sessions_start`. Inputs are the path, query and body fields side by side.
- `tools/list` returns only the tools the key may use right now.
- Read tools are marked read-only; tools that remove or end something are marked destructive.
- `docs_search` and `docs_fetch` read these docs for any valid key.
- Every tool publishes an `outputSchema` (from revision `2025-06-18`), and a successful call returns the same JSON as HTTP in `structuredContent` and as text. Fields can be added at any time — ignore the ones you do not know.
- With `2026-07-28`, `tools/list` is cacheable for 5 minutes per key (`cacheScope: private`).

## Writes and lost replies

Write tools accept a `command_id`. If the agent omits it, the server generates one and returns it in the result. After a disconnect, call `receipts_get` with that id instead of calling the write again.

## Errors and feedback

Failures come back as tool results with `isError: true` and the same `error.code` as HTTP. For failures Browlix could improve (`UNKNOWN`, `VALIDATION_FAILED`, `CONFLICT`, `UNSUPPORTED`…) the result adds a hint about `feedback_submit` — see [Feedback from agents](https://browlix.com/en/docs/feedback).

## Clients checked

Each row was run against the Browlix MCP server; a client that could not be exercised says so.

| Client | Version | Protocol | Result | Checked | Notes |
|---|---|---|---|---|---|
| Claude Code | 2.1.311 | `2026-07-28` | works | 2026-10-27 | server/discover, then tools/list (`claude mcp list` → Connected) |
| @modelcontextprotocol/client (TypeScript SDK v2) | 2.4.0 | `2026-07-28` | works | 2026-10-27 | pinned and auto negotiation; list, call, typed error, outputSchema validated by the client |
| @modelcontextprotocol/sdk (TypeScript) | 1.32.2 | `2025-11-25` | works | 2026-10-27 | initialize handshake; outputSchema validated by the client |
| @modelcontextprotocol/sdk (TypeScript) | 1.17.5 | `2025-06-18` | works | 2026-10-27 | initialize handshake; outputSchema validated by the client |
| @modelcontextprotocol/sdk (TypeScript) | 1.11.5 | `2025-03-26` | works | 2026-10-27 | no MCP-Protocol-Version header; tool list without outputSchema |
| Codex CLI | 0.164.0 | — | config only | 2026-10-27 | `codex mcp add … --bearer-token-env-var` accepted; a live session needs an OpenAI sign-in, not run in the lab |
| Cursor | — | — | not run | 2026-10-27 | desktop app, not run in the lab; configuration follows Cursor's docs |
| VS Code | — | — | not run | 2026-10-27 | desktop app, not run in the lab; configuration follows VS Code's docs |