No tools of its own, everything passes through.
MCP Stub adds no task tools. It exposes supported capabilities published by the connected service; your agent must support the returned content and any skills extension. The stub answers a few commands of its own for the people who install and support it, and it takes its settings when your agent starts it with serve.
Five kinds of content reach your agent.
| Content | What the agent gets | Limit |
|---|---|---|
| Tools | The service's tools, and a changed list when the service publishes one. The previously discovered list stays visible during an outage. | A visible tool can still fail, and a new or empty service shows an empty list |
| Results | Text, images, audio, embedded resources and resource links | Display and follow-up reads depend on your agent and your permissions |
| Resources | Published resources it can read | Lists can be empty while disconnected, and resource templates are not offered |
| Prompts | Published prompts it can request | They arrive as text |
| Skills | Skills the service publishes, listed and read through the connection. Needs release 0.5.0 or later and a service that offers skills. | Available when the service offers skills |
Why: the stub protects discovery, not execution. A failed call is returned to the agent and never repeated, and a restart does not keep a remote sign-in, transaction or terminal: those belong to the service.
What the program answers itself.
| Command | Use it to | Notes |
|---|---|---|
mcp-stub serve | Run the connection for your agent over standard input and output. Your agent's configuration starts it; running it by hand lists nothing. | Settings below |
mcp-stub version | Identify the installed build | Prints the version, with a commit suffix on some builds |
mcp-stub legal | List the third-party components built into this binary. --full adds the notices, and --json or --markdown change the format. | Works offline and starts no connection |
mcp-stub completions SHELL | Print shell completion text | bash, elvish, fish, powershell and zsh |
Choose the service, then the labels.
An argument wins over its environment variable. Choose either --server or --registry-key, never both.
| Argument | Environment | Default or rule |
|---|---|---|
--server ENDPOINT | MCP_STUB_SERVER | An existing service: a Unix socket path or an HTTP address |
--registry-key KEY | MCP_STUB_REGISTRY_KEY | Starts a registry on demand and reuses a reachable one with the same key |
--registry-json PATH | MCP_STUB_REGISTRY_JSON | Required with a key, as an absolute path |
--registry-binary PATH | MCP_STUB_REGISTRY_BINARY | Optional absolute path; otherwise the folder of mcp-stub, then PATH |
--session-tag TAG | MCP_STUB_SESSION_TAG | default; a label for diagnosis, not an access grant |
--identity-tag TAG | MCP_STUB_IDENTITY_TAG | A fresh identifier for each start; keep it unless the service owner asks for another |
Display, audio and GPU settings from the stub's environment are passed to a registry it starts. MCP_STUB_FORWARD_ENV replaces that selection and MCP_STUB_REGISTRY_ENV adds KEY=VALUE overrides. These apply only when a new registry starts.
What to expect when something fails.
| Limit | Value |
|---|---|
| Sign-in | Handled by the connected service |
| Recovery | Automatic, with no fixed deadline; failed calls are not repeated |
| Notifications | Advisory and can be missed; verify from the response or the destination |
| On-demand readiness | Waits about 30 seconds, which does not guarantee useful tools |
| Exit codes | 2 for a usage error, 1 for a startup failure after the arguments were accepted |
Use on-demand startup only on a single-user host. On shared hosts, use an existing service with an owner-approved private socket. Confirm a network endpoint's access restrictions with its owner. Keep HTTP on loopback, or put an authenticated, encrypted proxy that you operate in front of it. See Troubleshooting for recovery steps.