LangBot MCP Operations

LangBot exposes an MCP server so AI agents can manage an instance programmatically. It mirrors a curated subset of the HTTP service API.

Endpoint

http://<langbot-host>:5300/mcp

Transport: streamable HTTP (stateless, JSON responses). Same host/port as the web UI and HTTP API.

Authentication

Reuses the same API keys as the HTTP API. Send either header:

X-API-Key: <api-key>
# or
Authorization: Bearer <api-key>

Two kinds of key are accepted:

1. Web-UI key — created in the web UI (sidebar → API Keys), prefixed lbk_. The secret is shown once; only its SHA-256 hash is stored. Each key is bound to one Workspace and has explicit scopes, status, optional expiry, and last-used metadata. The key determines the Workspace; callers cannot switch it with X-Workspace-Id.
2. Global API key — set in data/config.yaml under api.global_api_key. Requires no login session and no DB record; does not need the lbk_ prefix. It is accepted only by a community instance with exactly one local Workspace and is disabled for SaaS multi-Workspace operation. Leave empty to disable. See the langbot-deploy skill for config details.

Invalid, revoked, or expired keys get 401 Unauthorized. A valid key whose scopes do not authorize a tool gets 403 Forbidden.

Client configuration

{
  "mcpServers": {
    "langbot": {
      "url": "http://<langbot-host>:5300/mcp",
      "headers": { "X-API-Key": "<api-key>" }
    }
  }
}

Tool surface

The tools wrap the LangBot service layer. Current tools (v1):

Mutating tools (create_*, update_*) take a JSON object matching the same shape as the corresponding HTTP API request body. Discover resources with the list_* / get_* tools before mutating; identifiers are UUIDs. Reads require resource.view; mutations require resource.manage. All service calls inherit the immutable Workspace context authenticated at the MCP transport boundary.

How to use

1. Get an API key (web UI key, or set api.global_api_key in config.yaml).
2. Point your MCP client at http://<host>:5300/mcp with the key header.
3. Call get_system_info to confirm connectivity.
4. Use list_* tools to discover, then get_* / create_* / update_* / delete_* as needed.

Implementation & maintenance (for LangBot developers)

• Server: src/langbot/pkg/api/mcp/server.py (FastMCP). Tools call the service layer directly, so the MCP surface stays aligned with the API.
• Mount: src/langbot/pkg/api/mcp/mount.py — an ASGI dispatcher fronting Quart, authenticating /mcp requests, running the streamable-HTTP session manager.
• Smoke test: tests/manual/mcp_smoke.py.

When you add, remove, or change an HTTP API endpoint that should be agent-accessible, update the corresponding MCP tool and this skill. The MCP tool surface and the API must stay aligned (see AGENTS.md).

Pitfalls

• /mcp is the server LangBot exposes. The /api/v1/mcp routes are the client side (managing external MCP servers LangBot connects to). Don't confuse them.
• A 401 means the key is wrong, missing, revoked, expired, or (for the global key) api.global_api_key is empty or the instance is not an OSS singleton.
• A 403 means the key is valid but lacks the permission required by the tool.
• The global key is plaintext in config.yaml — only enable it on trusted/internal deployments and serve over HTTPS.