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

# MCP servers

> Connecting stdio and HTTP MCP servers

graph consumes any [Model Context Protocol](https://modelcontextprotocol.io) server. Each `[mcp.<name>]` entry in config becomes a set of `<name>__*` tools.

<Note>
  This page is graph as an MCP **client**. For the other direction — serving your plans to another agent — see [graph as an MCP server](/tools/mcp-server).
</Note>

## Transports

**stdio** — graph spawns and manages the process:

```toml theme={null}
[mcp.github]
command = "docker"
args = ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}" }
```

**Streamable HTTP** — for hosted servers:

```toml theme={null}
[mcp.linear]
url = "https://mcp.linear.app/mcp"
headers = { Authorization = "Bearer ${LINEAR_API_KEY}" }
```

`command` and `url` are mutually exclusive; `${VAR}` in `env`/`headers` values resolves from your environment at load time. If a variable is unset, the server refuses to connect — naming the variable — rather than starting with an empty secret; the rest of the config (and every other server) keeps working.

<Note>
  Auth is static headers/env — servers requiring an interactive OAuth flow aren't supported directly. Many hosted servers (Linear included) accept API keys as bearer tokens.
</Note>

## Lifecycle

Servers connect lazily on first use and are cached for the process. stdio children are shut down cleanly on exit — and force-killed as a backstop on abnormal exits — so nothing lingers attached to your terminal. Server stderr is silenced.

```bash theme={null}
graph mcp list              # configured servers and transports
graph mcp test linear       # connect + count tools + how many declare output schemas
graph mcp tools [linear]    # tool listing grouped by server — names + descriptions
```

The tool listing prints one section per server — a header with the tool
count, then each tool's name (with a `[read-only]` marker when the server
annotates it) over its one-line description:

```
linear — 57 tools
  get_issue [read-only]
  Retrieve detailed information about an issue by ID, including attachments and git branch name
  save_issue
  Create or update a Linear issue. If `id` is provided, updates the existing issue; otherwise creates a new one.
  ...
```

`graph tools list` renders the full catalog in the same format, one section
per source.

## Filtering and overrides

```toml theme={null}
[mcp.everything]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-everything"]
include_tools = ["echo", "get-sum"]        # expose only these
exclude_tools = ["create_repository"]      # or hide these

# Patch a tool's metadata — most usefully, declare an output schema the
# server omits, which upgrades planner references for that tool:
[mcp.everything.tool_overrides.get-sum]
description = "Adds two integers."
output_schema = { type = "object", properties = { text = { type = "string" } } }
output_example = { text = "12" }     # optional worked example, shown to the planner
```

## Result handling

Tool results prefer MCP `structuredContent` when the server provides it; otherwise text content that parses as JSON is used as-is; otherwise the text is wrapped as `{"text": …}`. Server-side errors (`isError`) come back as structured tool errors — visible in traces, recoverable by the agent, and replan fuel for `plan_and_execute`.


## Related topics

- [graph as an MCP server](/tools/mcp-server.md)
- [CLI reference](/reference/cli.md)
- [Configuration](/reference/configuration.md)
- [Changelog](/changelog.md)
- [Errors & replanning](/plans/errors-and-replanning.md)