Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.
MCP hub
With the Library's switch "MCP hub" on (#2679, @minggang123 on X), each agent is given one MCP server, magpie, in place of the Library's MCP servers ticked for it. magpie serves it at /mcp/magpie/hub/<agent> (Streamable HTTP) and hands each call on to the Library server behind it. Any other app (Cursor, VS Code, Windsurf, an app on another computer) connects at /mcp/magpie/hub, which serves every server in the Library. A server written once is then set up once, for every agent and app, and a command server runs once, not once in each. The servers themselves are the Library's; the endpoint is the gateway's, guarded as Plugin tools' /mcp/magpie/tools is. The switch is off by default.
Responsibilities and sources of truth
| Part | Responsibility | Source |
|---|---|---|
| Switch | Library.MCPHub (mcpHub in library.json) is the source of truth. SetMCPHub sets it through change, so every agent is synced at once; turning it off also ends every server the hub started (hubStopAll). The page posts servers/hub {on}. |
SetMCPHub in mcp_hub.go; servers/hub in gui/library.go |
| Entry | syncMCP gives an agent hubServerFor(t), named magpie (HubEntry), in place of each server it would have written, and records it in Applied.MCP like any server, so turning the switch off takes out only that entry and writes each server's own again. The URL is the gateway as that agent reaches it (gatewayOf), so a WSL distro or a LAN computer gets its address, with Authorization: Bearer <key> when that address needs a key (agent.KeyAt). A LAN key or relay change re-syncs (LANChanged). magpie's own image server (isSelf) is never put behind the hub. |
hubFor, hubServerFor, inHub in mcp_hub.go; syncMCP in sync.go; mcp_signin.go |
| Who keeps their entries | An agent keeps each server's own entry, and AgentView.Hub says why: no-remote (it reaches no server over HTTP: mcpFile.supports refuses the entry, as for Claude Desktop), taken (a Library server is itself called magpie), own (the agent has an entry called magpie that magpie didn't write; it is left as it is). on is an agent given the hub's entry. An agent given none of the hub's servers has no value. |
hubFor in mcp_hub.go; AgentView.Hub, View.MCPHub, View.HubPath in sync.go |
| Serve | tools/list lists the tools of the servers ticked for that agent (at /mcp/magpie/hub, agent "": every server in the Library, ticked for any agent or none), but those in DisabledTools, as <server>__<tool>: each part in [A-Za-z0-9_-] (other characters _), at most 64 characters (cutName), _2, _3 on a name two would share. Each tool's description and inputSchema go on as the server listed them (an object schema with no properties when it has none). tools/call runs one; an unknown name, or another agent's, is error -32602. initialize and ping are answered; other methods are -32601. Tools only: no resources or prompts. |
hubMCPCall, hubNamed in hub_mcp.go |
| Guard | serveMCP, as /mcp/magpie/tools: a local request, or one with a gateway key; a browser page's Origin that corsAllowed doesn't allow is 403; POST only; a 4 MiB body (hubBody). The outer lanGuard/corsGuard already refuse Origin: null, a foreign site and a rebound Host. Each call is held to the calling key's limit (reserveFor) before anything runs. |
hubMCP, hubMCPRun in hub_mcp.go; serveMCP in search_mcp.go |
| Backends | One backend per Library server, shared by every agent (hubPool, keyed by the server's name; an edit or a sign-in since makes it a new one and ends the old). A command is started as CheckServers starts one (startServer: proc tree, home as its folder, ${NAME} env expanded), on its first list or call, and initialized once. A URL (http, sse) is reached with its headers and the Library's MCP sign-in (mcpauth), and a session the server forgot is opened again once. A notifications/tools/list_changed from a server makes the next list ask it again. |
backendOf, connect, dialHub, dialStdio, dialSSE, dialHTTP in mcp_hub.go; startServer, httpSession in mcp_check.go |
| Lifetime | A server with no call for hubIdle (10 minutes) is ended; the tools it listed are kept, so a list doesn't start it again, and the next call does. A command that died is started again on the next call. Turning the switch off, an edit, and the gateway stopping (StopHub on drain) end them: stdin closed, then the process tree. The switch can be turned off, or a server edited or unticked, by another magpie (the window while magpie serve runs, the CLI), and an agent given each server's own entry again never asks the hub, so the serving gateway also prunes every hubPruneEvery (5s) while it holds a server: each one the library no longer has as it was started, or every one once the switch is off, is ended (hubPrune). A server ticked for no agent is still served at /mcp/magpie/hub, so it is kept. |
use, done, stop, hubStopAll, hubPrune in mcp_hub.go; StopHub, keepHubPruned in hub_mcp.go |
| GUI | Below the server list in the Library's MCP tab: a row with the switch (.lib-switch, role=switch) saying what it does; on, a line counting what it serves (.lib-hubstats: servers, tools, the agents given it), then a row "Other apps" with the address (.lib-hubURL, copied with a click) and Connect…, and under them the agents that keep their own entries, grouped by why (.lib-hub-why[data-why]). The address is mcpAddress: the public one in a browser, the gateway in the app. Connect… opens a sheet (connectHub, .lib-hubsheet) of two tabs. Agents: agents → magpie → servers, drawn as icons with magpie's bird in the middle, a line of where things stand, then every agent mcpAgents lists (each detected, shown agent that takes MCP servers) in groups (.lib-hubgrp[data-group]): off (not connected), on (connected), kept (keeps each server's own entry). Each row (.lib-hubagent[data-state]: on, none, own, taken, no-remote) has a switch that posts servers/agents-all {agents:[id], on}, as By agent's Turn all on/off does: on gives it every Library server, so hubFor gives it the entry; off takes every Library server from it. A kept agent has a word for why and the reason in full behind (i) (.lib-hubinfo, .lib-hubwhy); an agent that reaches no server over HTTP says so even with none ticked. Connect all (.lib-huball) posts every none agent at once. With more than 8 agents a search (.lib-hubsearch) narrows every group, and the connected and the kept fold to one row each (.lib-hubfolded) until unfolded. The sheet stays open while it changes, and an agent is never handed to the user as a command to run. Other apps: the address (.lib-hubaddr), and a row per app (.lib-hubapp[data-app]): Cursor (only when it isn't one of the agents), VS Code, Windsurf and any JSON app, each with where its entry goes and a Copy entry (.lib-hubcopy) that copies its JSON. In the app, Cursor and VS Code also get Add (.lib-hubadd): the page posts servers/hub-open {app} and the window opens that app's install link (HubLink), which the app asks the user to confirm. The page never sends a link; an app with none is an error, and nothing is opened. In a browser there is no Add. |
hubPart, hubStats, connectHub in client.js, library.css, i18n.js; HubLink in mcp_hub.go; servers/hub-open in gui/library.go |
The CLI's magpie library mcp hub on|off calls SetMCPHub, and magpie library lists the agents given magpie's entry and those that keep their own, with why (libraryStatus in library_cli.go).
The gateway can't import the library (the library imports the gateway), so the gateway declares Hub and MCPHub, and the library sets MCPHub in its init.
Runtime path
- The user turns the switch on.
SetMCPHub(true)savesmcpHuband syncs: each agent that can take it gets the onemagpieentry, and the servers behind it are taken out of that agent's file. Nothing is started yet. - The agent starts and posts
initialize, thentools/list, to/mcp/magpie/hub/<agent>.hubMCPpasses the guard.Toolsreads library.json for the servers ticked for that agent, and lists each in parallel, byhubListWait(40s): a server not reached by then is left out of that list, not an error. Another app does the same at/mcp/magpie/hub, under the same guard: from another computer it needs a gateway key, as every LAN request does. tools/callfinds the tool by its hub name in the same list, holds it to the key's limit, and callsCallunderhubCallWait(50s, under the 60s an MCP client gives a call). The server's result goes back as it gave it.- An error comes back as
isErrortext naming the server:The MCP server S couldn't run T: <why>, where why is how it exited and its last line on stderr, a sign-in it needs, its command not found, orit didn't answer in 50s.
Constraints and failure behavior
- Off means off: no tool is listed, a call says the hub is off, and no server is started (
TestHubMCPOff,TestHubToolsAndCalls). - magpie takes out only the
magpieentry it wrote (Applied.MCP). An entry called magpie of the agent's own, or a Library server called magpie, keeps every server's own entry for that agent, said on the page. - A tool turned off in the Library is neither listed nor run, for every agent, including those that have no setting of their own for it.
- A call that times out leaves the server running for the next; a server that died is started again. A server that can't be started is an error on each call, not a retry loop.
- Every process the hub starts is in a
proctree magpie ends when the switch goes off, the server is edited, it has been idle, or the gateway stops. A test ends them in cleanup (hubSandbox). - A gateway key holder on the LAN reaches the Library's command servers through the hub while it is on, as they reach plugin tools. They run with the user's rights on this computer.
- The tools a server listed are cached until it says they changed, it is edited, or the switch is turned off. A server that changes its tools without saying so shows them after one of those.
Verification
go test -tags nogui ./internal/gui -run TestHubOpen
go test -tags nogui ./internal/library -run 'TestHub|TestFakeMCPServer|TestCheck'
go test -tags nogui ./internal/gateway -run 'HubMCP|OwnMCPRejects' -timeout 45m
go test -tags nogui ./internal/cli -run TestLibraryMCPHub
node --test internal/gui/tests/library-mcp-hub.test.cjs
The library tests run a fake stdio MCP server (TestFakeMCPServer in mcp_check_test.go: a tool that dies, one that never answers) and an httptest Streamable HTTP one (mcpHandler). The gateway tests use a fake Hub.