> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP servers

> Connect your own MCP servers to Helix. Their tools reach the model directly.

Helix speaks the Model Context Protocol (MCP). It ships no MCP server of its own: the servers you
configure are the ones it uses, and their tools reach the model directly, next to Helix's own tools.

## Add a server

List your servers in an `mcp.json` file, in the `mcpServers` shape other MCP clients use:

| File | Applies to |
| - | - |
| `~/.mutagent/agent/mcp.json` | Every Helix session on your machine. |
| `.pi/mcp.json` in your project | Sessions in that project, once you trust it. |

```json mcp.json theme={null}
{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
    "docs": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" } }
  }
}
```

A local server runs from `command` and `args`; a remote one is reached at `url`. The next Helix
session loads them.

## How the model sees the tools

Each tool is offered to the model as `mcp__<server>__<tool>`, for example
`mcp__docs__search`. The model calls it like any other tool.

> [!NOTE]
>
> Leave a server's `exposure` field out, or set it to `"direct"`. A server set to `"codemode"` or
> `"deferred"` has no tools Helix can call, and Helix warns about it.

## Manage servers with `/mcp`

Type `/mcp` in a Helix session to open the MCP manager. It lists every server you configured with its
state (for example `connected · 4 tools`, `needs sign-in`, `failed` or `disabled`), its exposure, and
where it is configured (for example `project`). Servers that need you come first. With no servers configured, it tells you
which files to add them to.

Pick a server to act on it:

| Action | Does |
| - | - |
| Sign in | Opens the browser to sign in to a server that asks for it. If the browser cannot reach your machine, paste the URL it was redirected to. |
| Tools | Lists the tools the server offers. |
| Reconnect | Connects to the server again, for example after it failed or you changed its settings. |
| Sign out | Deletes the stored sign-in credentials for the server. |
| Exposure | Changes how the server's tools reach the model. Keep it on `direct` (see the note above). |
| Enable / Disable | Turns the server on or off. Saved to the `mcp.json` that defines the server, as `"enabled": false` when off. |

Sign-in applies to remote servers that have no `Authorization` header and ask for one when Helix
connects: Helix signs you in with OAuth and stores the credentials for you.

You can also run an action directly:

| Command | Does |
| - | - |
| `/mcp` | Open the manager. |
| `/mcp login [server]` | Sign in to a server. Needs an interactive session. |
| `/mcp logout [server]` | Sign out of a server and delete its stored credentials. |
| `/mcp reconnect [server]` | Reconnect to a server. |

Leave out the server name and Helix picks the only one that fits, or asks you which one. When a
server fails to connect or needs a sign-in at the start of a session, Helix tells you once and points
you to `/mcp`.

## Where MCP tools are available

| | MCP tools |
| - | - |
| `helix` and `helix agent` | Offered to the model directly. |
| `helix --prime` | Called from code: a cell can search your MCP tools, read a tool's parameters and call it. See [Prime](https://docs.mutagent.io/helix/modes.md#helix-prime-the-code-first-mode). |
| Sub-agents | Not available. A sub-agent works with Helix's own tools. |

> [card] [Project context](https://docs.mutagent.io/helix/features/project-context.md)
>
> The other thing every session loads from your project: `AGENTS.md` / `CLAUDE.md`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.