Connect to LobeHub as an MCP Server
LobeHub can act as an MCP server, so a coding assistant or any MCP client can list your Agents, run one, and read Topics, messages, files, and Libraries.
The same pull request adds a user guide for this at docs/usage/integrations/mcp-server; this page is the developer reference.
This is the opposite direction from the MCP servers you add to LobeHub Agents (managed through /api/v1/mcp-servers, available today).
Endpoint and Authentication
- URL:
https://app.lobehub.com/api/v1/mcp(or<your origin>/api/v1/mcp) - Transport: Streamable HTTP, stateless. Clients send JSON-RPC with
POST;GETandDELETEreturn405. - Authentication: the same as the REST API,
Authorization: Bearer <API key or OIDC token>. SendX-Workspace-Idwith an OIDC token to work in a Workspace; a Workspace API key uses its own Workspace.
The server only lists the tools your credential's scopes reach. Create a dedicated API key with only the scopes below that you want the assistant to have.
Tools
| Tool | What it does | Scopes |
|---|---|---|
list_agents, get_agent | List Agents, read one | agent:read |
run_agent | Run an Agent and wait for the reply (waitSeconds, default 50, up to 120) | run:write, model:invoke |
get_run | Read a run's status and result | run:read |
search_topics, get_topic, search_messages | Find and read conversations | chat:read |
list_files, read_file | List and read files | file:read |
upload_file | Upload a file | file:write |
list_knowledge_bases | List Libraries | knowledge:read |
Resources: lobehub://agents, lobehub://agents/{agentId}, lobehub://topics/{topicId}. Prompt: summarize_topic.
When run_agent does not finish within waitSeconds, it returns the run id; call get_run later.
Client Configuration
Claude Code
Cursor
Add to ~/.cursor/mcp.json:
Codex
Add to ~/.codex/config.toml and export LOBEHUB_API_KEY:
Check the Connection
After adding the server, ask the assistant to "list my LobeHub agents". It should call list_agents and show your Agents. If it reports 401, check the key; if a tool is missing, the key lacks that tool's scope.