<!-- Markdown mirror. Canonical: https://empryo.com/docs/tools/mcp -->

# MCP Servers

> Connect Empryo to Model Context Protocol servers over stdio, Streamable HTTP, or SSE. Namespaced tools, auto-restart, retry with backoff, and headless support.

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:

```json
{
  "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.

```json
{
  "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:

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