mait.sh1.69.2

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

Docs / Agent tools (MCP)

MCP Stub

Keep a configured tool connection discoverable through interruptions and reconnect when its upstream recovers.

For agent-platform operators and developers using a shared local MCP registry.

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

Beta
All components

What it doesBasics

  • Per-session identity tagging
  • Registry auto-start
  • Reconnect with cached discovery
  • Tool-list change notifications
  • Environment forwarding for desktop-capable tools

First useBasics

  1. Verify a known read through the supplied connection.
  2. Let the stub connect or start the registry.
  3. Refresh discovery explicitly when needed after upstream recovery.

Everyday tasksEveryday use

Keep a client attached across registry restarts

A long-running agent session must continue through an upstream registry restart.

  1. Start the stub with one reviewed upstream endpoint.
  2. Initialize the downstream client and discover tools.
  3. Restart the upstream, allow reconnect, then refresh discovery explicitly when the client needs the current catalog.

What you getThe client keeps one stdio connection and its last catalog, and execution resumes after recovery.

How to check: Connection tracing confirms recovery, and a list-change notification can signal catalog changes.

Add authorized tools mid-session

A registry backend becomes available only after user authorization.

  1. Connect the agent through the stub to the registry.
  2. Complete the registry authorization while the session remains open.
  3. Receive the upstream tool-list change and refresh discovery.

What you getNewly authorized tools appear without restarting the agent client.

How to check: Relayed list-change notification and refreshed tool list demonstrate the transition.

Settings to decideAdvanced

Upstream selection
Configure exactly one Unix socket or HTTP upstream; avoid ambiguous simultaneous selections.
Registry auto-start
Enable auto-start only when the stub should own registry launch. The documented forwarding set is the default; MCP_STUB_FORWARD_ENV replaces it, while MCP_STUB_REGISTRY_ENV adds explicit values and wins on duplicate keys.
Session identity
Set stable, non-secret tags when registry-side attribution is useful. Labels aid diagnosis. Upstream, the stub reports itself as MCP Stub:session=<tag>;identity=<tag>.
Notification relay
Keep relay enabled when clients need signals about changing tools, resources, prompts, or backend-specific events. Refresh explicitly when current discovery matters.

CommandsAdvanced

$ mcp-stub version
$ mcp-registry serve --transport unix --socket /tmp/mcp-registry.sock --registry-json /etc/mait/mcp-backends.json
$ mcp-stub serve --session-tag agent-1-session --identity-tag agent-1 --server /tmp/mcp-registry.sock

Problems and fixesHelp

What you seeCheckFix
The stub cannot connect to its upstream.Confirm that only one upstream flag is set and the resolved socket or URL is reachable.Correct the endpoint or enable documented registry auto-start, then allow reconnect to proceed.
Calls fail although a cached tool list is still visible.Inspect upstream health and wait for revalidation after reconnect.Restore the upstream, then refresh the client catalog explicitly when needed, and inspect the destination state before repeating a mutation.
The MCP client reports malformed JSON-RPC on stdio.Check wrappers and redirects for logs or stderr merged into stdout.Reserve stdout exclusively for MCP frames and route diagnostics to stderr.
What you see
The stub cannot connect to its upstream.
Check
Confirm that only one upstream flag is set and the resolved socket or URL is reachable.
Fix
Correct the endpoint or enable documented registry auto-start, then allow reconnect to proceed.
What you see
Calls fail although a cached tool list is still visible.
Check
Inspect upstream health and wait for revalidation after reconnect.
Fix
Restore the upstream, then refresh the client catalog explicitly when needed, and inspect the destination state before repeating a mutation.
What you see
The MCP client reports malformed JSON-RPC on stdio.
Check
Check wrappers and redirects for logs or stderr merged into stdout.
Fix
Reserve stdout exclusively for MCP frames and route diagnostics to stderr.

All MCP Stub problems and fixes →

Good to knowHelp

  • The tool list stays discoverable while the upstream reconnects.
  • Inspect the destination before repeating a change whose result is unclear.
  • Connection and identity labels support diagnosis and per-agent attribution.