> ## 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 Architech. The model calls their tools directly.

> [!NOTE]
>
> **Early Access.** Commands and behavior can change between releases.

Architech supports the Model Context Protocol (MCP). It ships no MCP server of its own: it uses the
servers you configure, and the model calls their tools directly, next to Architech'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 |
| - | - |
| `mcp.json` in Architech's active agent directory | Sessions using that agent directory; `/mcp` shows the configuration locations. |
| `.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`. Your next
Architech session loads them. Put servers specific to one repository in the project file. To see
where your running session reads its configuration, use `/mcp`.

## How the model sees the tools

In normal orchestrator and agent sessions, the model sees each direct tool as
`mcp__<server>__<tool>`, for example `mcp__docs__search`, and calls it like any other tool.

> [!NOTE]
>
> For normal orchestrator and agent sessions, leave out a server's `exposure` field or set it to
> `"direct"`. With `"codemode"` or `"deferred"`, the model in those sessions doesn't see the
> tools. Prime is different: its code helpers can call MCP tools, `"codemode"` ones included,
> without exposing them to the model directly.

## Manage servers with `/mcp`

Type `/mcp` in an Architech 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's configured (for example `project`). Servers that need you come first. If
you have none, 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 is for remote servers that have no `Authorization` header and ask for one when Architech
connects. Architech 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 Architech picks the only one that fits, or asks you which one. If a
server fails to connect or needs a sign-in when a session starts, Architech tells you once and
points you to `/mcp`.

## Where MCP tools are available

| | MCP tools |
| - | - |
| `architech` and `architech agent` | Offered to the model directly. |
| `architech --prime` | Called from code: a cell can search your MCP tools, read a tool's parameters and call it. The code helpers are `searchTools`, `describeTool` and `callTool`. |
| Sub-agents | Not available. A sub-agent works with Architech's own tools. |

> **[Project context](https://docs.mutagent.io/architech/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.