MCP servers

graph consumes any Model Context Protocol server. Each [mcp.<name>] entry in config becomes a set of <name>__* tools.

This page is graph as an MCP client. For the other direction — serving your plans to another agent — see graph as an MCP server.

Transports

stdio — graph spawns and manages the process:

[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:

[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.

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.

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.

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

[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.

Getting Started

Plans

Workbench

Tools

Models

Chat & ask

Cookbook

Reference

Architecture

Changelog

Transports

Lifecycle

Filtering and overrides

Result handling

​Transports

​Lifecycle

​Filtering and overrides

​Result handling

Transports

Lifecycle

Filtering and overrides

Result handling