MCP Registry
Names, counts and diagnostics vary with the installed release and your fleet; use the tool definitions your client returns before a call.
One entry
Aggregate local servers behind one entry.
You run a code history server and a cluster server, and you do not want each one set up again in every app.
Capturedmcp-registry 0.8.5 · mcp-git 0.7.5 · mcp-kubectl 0.7.5
YouAdd the git and kubectl servers and show me what I have.
Tool callmcp_registry_add { "name": "git", "transport": "stdio", "command": "/usr/local/bin/mcp-git", "args": ["serve"] }
What happens{ "message": "server 'git' added and started" }
Tool callmcp_registry_add { "name": "kubectl", "transport": "stdio", "command": "/usr/local/bin/mcp-kubectl", "args": ["serve"] }
What happens{ "message": "server 'kubectl' added and started" }
Tool callmcp_registry_list {}
What happenscount 2, both Connected: git with 8 tools and kubectl with 4.
AgentBoth backends are connected: git with eight tools and kubectl with four, each named after its backend.
Search and enable
Keep the standing tool list short.
You have many servers, and the agent should not read every tool in every conversation.
Capturedmcp-registry 0.8.5 · mcp-git 0.7.5
YouI need to rebase a branch. Find the tool and add it.
What happensThe git backend was registered with preload ["git_inspect", "git_log"]: the client's list holds 18 tools, two of them git__git_inspect and git__git_log.
Tool callmcp_registry_tool_search { "query": "rebase" }
What happensTwo results, both enabled false: git__git_rebase, "Rebase/merge workflow.", and git__git_commit, "Stage and commit following aiom-spec."
Tool callmcp_registry_tool_enable { "names": ["git__git_rebase"] }
What happensThe full definition of git__git_rebase comes back with its input schema and the client is notified; the list now holds 19 tools.
Agentgit__git_rebase is available in this session. It takes an action and, to start, a plan.
Fleet file
Keep the fleet in a file you can review.
You want the same servers on another machine or in another app, and you want to read the list before you trust it.
Capturedmcp-registry 0.8.5
YouExport the fleet, take kubectl out for now, and then bring it back from the file.
Tool callmcp_registry_export { "path": "out.json" }
What happens{ "count": 2 }. The file holds git and kubectl, each with command, args, env and url.
Tool callmcp_registry_remove { "name": "kubectl" }
What happens{ "message": "server 'kubectl' removed" }
Tool callmcp_registry_import { "path": "out.json" }
What happens{ "added": ["kubectl"] }: only the missing backend was added; git was left alone.
Agentkubectl is back and connected with its four tools. git was not touched.
Check on a backend
See which backend needs attention.
A request failed, or a tool you expected is missing, and you do not know which server is responsible.
Capturedmcp-registry 0.8.5 · mcp-git 0.7.5
YouWhich backends are healthy, and what has git logged?
Tool callmcp_registry_list {}
What happensBoth backends Connected.
Tool callmcp_registry_logs { "name": "git" }
What happensSeven lines: git starting, the server version, session mode per-connection, a session idle reaper and "Server ready, waiting for requests...".
AgentBoth are connected and git started cleanly. Nothing in its log needs attention.
Shared view
Reach it from more than one client.
Several apps on one machine should share one registry and one set of servers.
Illustrative conversation
YouRun the registry as a background service on a private socket.
What happensA shell command creates a private directory, then starts MCP Registry serve --transport unix --socket "$XDG_RUNTIME_DIR/mcp-registry/registry.sock".
Tool callmcp_registry_list {}
What happensCalled from a second client on the same socket: the same backends, each client with its own enabled tools.
AgentThe registry serves both clients from one fleet.