mait.sh1.69.2

Private beta: features and content may change. No warranty; use at your own risk.

Docs / Agent tools (MCP)

MCP Registry

Connect configured MCP backends through one discoverable tool catalog.

For teams operating several MCP servers for multiple simultaneous agent sessions.

Read from the top for the basics; the later sections go deeper.

Beta
All components

What it doesBasics

  • Backend discovery and supervision
  • Namespaced tool aggregation
  • Session-scoped tool views
  • Remote authorization flows
  • Resource and notification routing

First useBasics

  1. Connect one trusted backend and verify a known permitted read through the catalog.
  2. Connect a client directly, or add MCP Stub when per-agent attribution and reconnect continuity are needed.
  3. Check target operations separately from registry connection state.

Everyday tasksEveryday use

Expose one gateway to an agent

An agent needs several MCP capabilities without separate client configuration for every server.

  1. Register reviewed local and remote backends.
  2. Wait for each backend to reach Connected.
  3. Discover and perform a known permitted read through its namespaced tool.

What you getThe client receives one aggregated MCP surface with backend identities preserved.

How to check: Registry connection state describes the backend lifecycle; the separate permitted read checks target operation through that backend.

Authorize a protected backend

A remote MCP backend enters NeedsAuth and must gain user consent.

  1. Start the backend authorization flow.
  2. Open the returned authorization URL and complete consent.
  3. Confirm authorization state and allow the backend to reconnect.

What you getThe backend returns to Connected with its tools available.

How to check: Authorization status and backend lifecycle state record completion without exposing token values.

Settings to decideAdvanced

Backend transport
Use stdio when the registry should own and log the process; use Unix or HTTP for independently managed services.
Session tool visibility
Use restricted preload only with per-connection sessions over stdio or Unix transport; search and enable manage context size.
Notification relay
Enable relay_notifications only for backends whose custom events the client needs. Refresh the client catalog when a list-change notification arrives.
Credential ownership
Prefer ${VAR} references or OAuth configuration over literal headers. Define an owner, storage permissions, rotation, revocation and incident response for registry-held OAuth state.

CommandsAdvanced

$ mcp-registry serve
$ mcp_registry_add({"name":"git","transport":"stdio","command":"/path/to/mcp-git","args":["serve"]})
$ mcp_registry_list({}) # expect state: Connected and tools > 0

Problems and fixesHelp

What you seeCheckFix
A backend reports BinaryMissing, SpawnFailed, InitTimeout, or InitFailed.Read error_kind, verify the command and permissions, and inspect stdio stderr when available.Install or fix the binary, raise a legitimate init timeout if needed, then reload the backend.
A backend is NeedsAuth or rejects its first tool call.Inspect authorization status and confirm the endpoint advertises the expected OAuth discovery challenge.Run a fresh authorization flow using a callback mode reachable from the browser.
A backend remains Reconnecting(N) or the pool is exhausted.Inspect the last error, backend health, crash frequency, and configured pool size.Repair the backend and reload for an immediate retry, or reduce concurrency/re-register with a suitable pool size.
What you see
A backend reports BinaryMissing, SpawnFailed, InitTimeout, or InitFailed.
Check
Read error_kind, verify the command and permissions, and inspect stdio stderr when available.
Fix
Install or fix the binary, raise a legitimate init timeout if needed, then reload the backend.
What you see
A backend is NeedsAuth or rejects its first tool call.
Check
Inspect authorization status and confirm the endpoint advertises the expected OAuth discovery challenge.
Fix
Run a fresh authorization flow using a callback mode reachable from the browser.
What you see
A backend remains Reconnecting(N) or the pool is exhausted.
Check
Inspect the last error, backend health, crash frequency, and configured pool size.
Fix
Repair the backend and reload for an immediate retry, or reduce concurrency/re-register with a suitable pool size.

All MCP Registry problems and fixes →

Good to knowHelp

  • The registry is an administration endpoint for trusted clients.
  • Session tool lists organize discovery for each agent session.
  • Operators manage storage, rotation and revocation of registry-held OAuth credentials.