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

# MCP Servers

> Connect Empryo to Model Context Protocol (MCP) servers over stdio, HTTP or SSE, so the agent can use their tools next to the built-in ones.

MCP (Model Context Protocol) is an open standard for giving AI agents extra tools. Connect an MCP server to Empryo and the agent can call its tools, for example to open GitHub issues or query Sentry, alongside its built-in tools.

Use it when the agent needs a service Empryo does not cover out of the box.

## Quick start

Add a server to `mcpServers` in your config. This one runs the GitHub server as a local process:

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

Restart Empryo or open `/mcp` to check it connected. The server's tools are now available to the agent as `mcp__github__<tool>`.

If you copy a config from another tool that writes `mcpServers` as an object keyed by server name, that works too. Empryo reads the key as the server's `name`.

## Where the config lives

- **Global:** `~/.empryo/config.json` applies to every project.
- **Project:** `.empryo/config.json` applies to one repository. A project server with the same `name` as a global one replaces it.

A project's MCP servers start only after you trust the repository with `/trust`. This stops a cloned repo from running commands on your machine without your say.

## Three ways to connect

| Transport | Use it for | Needs |
|---|---|---|
| `stdio` (default) | A server that runs as a local program | `command`, optional `args`, `env`, `cwd` |
| `http` | A remote server over Streamable HTTP. Use this for new remote servers | `url`, optional `headers` |
| `sse` | Older remote servers that only speak Server-Sent Events | `url`, optional `headers` |

```json
{
  "mcpServers": [
    {
      "name": "sentry",
      "transport": "http",
      "url": "https://mcp.sentry.dev/sse",
      "headers": { "Authorization": "Bearer ..." }
    },
    {
      "name": "legacy-service",
      "transport": "sse",
      "url": "https://legacy.example.com/events",
      "disabled": true
    }
  ]
}
```

## Settings

| Field | Type | What it does |
|-------|------|-------------|
| `name` | string (required) | The server's name. Also the prefix of its tool names |
| `transport` | `"stdio"` \| `"http"` \| `"sse"` | How to connect. Default `"stdio"` |
| `command` | string | Program to start (stdio) |
| `args` | string[] | Arguments for `command` |
| `env` | `Record<string,string>` | Environment variables for the program |
| `cwd` | string | Working directory for the program (stdio) |
| `url` | string | Server address (http, sse) |
| `headers` | `Record<string,string>` | HTTP headers, such as `Authorization` (http, sse) |
| `timeout` | number | Time limit for each tool call, in ms. Default 30000 |
| `disabled` | boolean | Keep the entry but don't connect |
| `resident` | boolean | Always send this server's tools to the model instead of loading them on demand. Use it for a server you rely on every turn. The set is fixed when a session starts, so the prompt cache holds: a server pinned later, or one that was not connected at startup, is reached on demand until the next session, and a pinned server that disconnects keeps its tools, which answer that it is not connected |
| `redirect` | `"follow"` \| `"error"` | Whether a remote server may redirect. Set `"follow"` only if the server needs it |

## Tool names

Every MCP tool is renamed to `mcp__<server>__<tool>` so it can never clash with a built-in tool. A server named `github` with a tool `create_issue` gives the agent `mcp__github__create_issue`.

## Connection behavior

- All enabled servers connect when Empryo starts, up to four at a time.
- If a local (stdio) server crashes, Empryo restarts it, up to three times with a growing delay.
- A remote server that fails stays failed until you retry it from `/mcp`.
- When Empryo exits, it closes every connection and stops every local server.

## Manage servers in the terminal UI

Run `/mcp` to see each server's status and tools.

| Key | Action |
|----------|--------|
| Type | Filter servers by name |
| `Ctrl+A` | Add a server |
| `Ctrl+E` | Edit the selected server |
| `Ctrl+D` | Delete the selected server |
| `Ctrl+T` | Turn the selected server on or off |
| `Ctrl+R` | Reconnect a failed server |
| `Ctrl+P` | Ping a connected server |
| `Tab` | Switch to the tools list |
| `Enter` | Open the server's details |

## Headless runs

MCP servers also connect in headless mode, so scripts and CI jobs can use them:

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