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:

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

json

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

Tool	Purpose
`get_system_info`	Version, edition, instance id
`list_bots` / `get_bot` / `create_bot` / `update_bot` / `delete_bot`	Manage messaging-platform bots (secrets redacted on read)
`list_pipelines` / `get_pipeline` / `create_pipeline` / `update_pipeline` / `delete_pipeline`	Manage pipelines
`list_llm_models` / `get_llm_model` / `list_embedding_models` / `list_model_providers`	Inspect models & providers
`list_knowledge_bases` / `get_knowledge_base` / `retrieve_knowledge_base`	RAG knowledge bases (incl. semantic search)
`list_mcp_servers`	External MCP servers LangBot connects to (as a client)
`list_skills` / `get_skill`	Installed skills

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

Get an API key (web UI key, or set api.global_api_key in config.yaml).
Point your MCP client at http://<host>:5300/mcp with the key header.
Call get_system_info to confirm connectivity.
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.