Connect an MCP server

Add an MCP server’s tools to your catalog and check they work.

Add a server to config.toml and its tools join your catalog as <name>__<tool>, ready for agents and plan steps.

Before you start

You need the server’s launch command or its URL. If it needs a token, put the token in an environment variable rather than in the file.

Add the server

1. Add an [mcp.<name>] table

   The table name becomes the prefix of every tool from the server. Use command for a server graph starts itself over stdio, or url for a streamable HTTP server.

   stdio

   [mcp.everything]
   description = "MCP reference server for testing"
   command = "npx"
   args = ["-y", "@modelcontextprotocol/server-everything"]
   

   description is optional, but setting it generally improves how well the planner chooses the server’s tools. Values in env and headers expand ${VAR} from your environment. If a variable isn’t set, graph doesn’t connect to that server and names the missing variable.

2. Test the connection

   graph mcp test everything
   

   ok: 'everything' initialized in 1.37s — 13 tools (1 declare output schemas)
   

Check it worked

List the server’s tools, then call one through graph:

graph mcp tools everything
graph tool test everything__echo --input message=hello

{
  "text": "Echo: hello"
}

graph returns a tool’s structured content when the server sends it. Otherwise it parses the text the tool returns as JSON, or wraps plain text as {"text": ...}, as here.

To load only some of a server’s tools, or fix a tool’s description, see Filter and override a server’s tools. If the server won’t connect, see Test an MCP server.

Related config.toml options

mcp · object

MCP servers, as [mcp.<name>]. Their tools join the catalog as <name>__<tool>.

mcp.<name>.description · string

What the server is for, read by drafters choosing tools.

mcp.<name>.command · string

Executable for a stdio server. Use command or url, not both.

mcp.<name>.args · string[]

Arguments for command.

mcp.<name>.env · map<string, string>

Environment for a stdio server. Values expand ${VAR}.

mcp.<name>.url · string

Endpoint for a streamable HTTP server.

mcp.<name>.headers · map<string, string>

HTTP headers. Values expand ${VAR}.

mcp.<name>.include_tools · string[]

Load only these tools.

mcp.<name>.exclude_tools · string[]

Skip these tools.

mcp.<name>.tool_overrides · object

Per-tool corrections, as [mcp.<name>.tool_overrides.<tool>].

mcp.<name>.tool_overrides.<name>.description · string

Replaces the server’s description of the tool.

mcp.<name>.tool_overrides.<name>.output_schema · object

The tool’s output shape.

mcp.<name>.tool_overrides.<name>.output_example · object

An example of the tool’s output.

Go to full reference