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.

Tools3 minutes to read

Copy & share

On this page8 sections

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 startLink to this section

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 livesLink to this section

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 connectLink to this section

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
    }
  ]
}

SettingsLink to this section

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 namesLink to this section

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 behaviorLink to this section

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 UILink to this section

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 runsLink to this section

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"