Empryo connects to MCP servers, exposing their tools alongside built-in tools. Three transports are supported: stdio (local subprocess), Streamable HTTP (remote), and SSE (legacy remote).

Quick start

Add a simple stdio server to your config:

{
  "mcpServers": [
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  ]
}

Tools from this server are now available as mcp__github__<tool>.

Configuration

Add mcpServers to your global config (~/.empryo/config.json) or project config (.empryo/config.json). Project config overrides global by server name.

{
  "mcpServers": [
    {
      "name": "github",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." },
      "timeout": 30000
    },
    {
      "name": "sentry",
      "transport": "http",
      "url": "https://mcp.sentry.dev/sse",
      "headers": { "Authorization": "Bearer ..." },
      "timeout": 30000
    },
    {
      "name": "legacy-service",
      "transport": "sse",
      "url": "https://legacy.example.com/events",
      "headers": { "X-API-Key": "..." },
      "disabled": false
    }
  ]
}

Config reference

Field	Type	Description
`name`	string (required)	Display name and tool namespace prefix
`transport`	"stdio" \	"http" \	"sse"	Transport type (default: "stdio")
`command`	string	Command to spawn (stdio transport)
`args`	string[]	Arguments for command
`env`	`Record<string,string>`	Environment variables for subprocess
`url`	string	URL for http/sse transports
`timeout`	number	Per-tool-call timeout in ms (default: 30000)
`disabled`	boolean	Disable without removing config
`headers`	`Record<string,string>`	HTTP headers for http/sse transports

Tool namespacing

MCP tools are namespaced as ` mcp__<server>__<tool> to prevent collisions with built-in tools. A server named "github" with tool "create_issue" becomes mcp__github__create_issue`.

Transport types

stdio - Spawns a local subprocess. The server communicates via JSON-RPC over stdin/stdout. Best for local tools and development.

http - Streamable HTTP (recommended for remote servers). Modern MCP transport with efficient streaming.

sse - Server-Sent Events. Legacy remote transport. Use http for new servers.

Lifecycle

Startup: All enabled servers connect with bounded concurrency (max 4 simultaneous)
Retry: Failed servers retry up to 3 times with exponential backoff (1s, 2s, 4s)
Auto-restart: Servers that crash automatically restart (stdio transport only)
Cleanup: On exit, all connections are closed and subprocesses terminated

TUI shortcuts

Open the MCP manager with /mcp or Ctrl+K → search "mcp".

Shortcut	Action
Type	Filter servers by name
`Ctrl+A`	Add new server
`Ctrl+D`	Delete selected server
`Ctrl+T`	Toggle enable/disable
`Ctrl+E`	Edit server config
`Ctrl+R`	Retry failed connection
`Tab`	Switch to tools browser
`Enter`	Open server detail view

Headless mode

MCP servers connect automatically in headless mode. Tools are available to the agent immediately:

empryo --headless "use the github MCP to list open issues"