Guide

MCP Server Setup

Set up the Traverse MCP stdio server so AI agents can discover and call your governed capabilities as tools.

v0.7.0 ~15 minutes Rust 1.94+

Prerequisites

Before you start

You need three things before starting the MCP server.

Rust installed (rustc --version should print 1.94 or later)
The Traverse repo cloned locally
A bundle built and ready — run the quickstart first if you have not

New here? Complete the Quickstart first. It walks you through building the expedition bundle that this guide uses.

Start the server

Start the MCP server

The MCP server reads from stdin and writes to stdout. It does not bind a port. Run it with cargo run during development.

start traverse-mcp

$ cargo run -p traverse-mcp

Traverse MCP server ready (stdio)

Waiting for JSON-RPC input...

The server stays running and processes one JSON-RPC message per line. In production you hand the binary path to your MCP client and let the client manage the process.

Client config

Configure your MCP client

Most MCP clients take a JSON config that maps a server name to a command. Point yours at the compiled traverse-mcp binary.

mcp-config.json

{
  "mcpServers": {
    "traverse": {
      "command": "/path/to/traverse/target/debug/traverse-mcp",
      "args": [],
      "env": {}
    }
  }
}
        

Replace /path/to/traverse with the absolute path to your local repo. The binary is at target/debug/traverse-mcp after a dev build, or target/release/traverse-mcp after a release build.

Test

Test with tools/list

Send a tools/list request to see all capabilities the server exposes. You can pipe it directly to test without an MCP client.

tools/list request

$ echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \

| cargo run -p traverse-mcp

response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "plan-expedition",
        "description": "Plan an alpine expedition for a team. Returns itinerary and equipment list.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "goal": { "type": "string" },
            "team_size": { "type": "integer" },
            "duration_days": { "type": "integer" }
          },
          "required": ["goal", "team_size", "duration_days"]
        }
      }
    ]
  }
}
        

Execute

Execute a capability via MCP

Use tools/call to invoke a capability. Pass the tool name and a JSON arguments object matching the input schema.

tools/call request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "plan-expedition",
    "arguments": {
      "goal": "Plan a two-day alpine expedition for a four-person team.",
      "team_size": 4,
      "duration_days": 2
    }
  }
}
        

response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Day 1: Ascent to base camp..."
      }
    ],
    "_traverse": {
      "trace_id": "trc_7f3a1b",
      "status": "completed",
      "duration_ms": 143,
      "capability": "plan-expedition@1.0.0",
      "events_emitted": ["expedition.planned"]
    }
  }
}
        

Response fields

Understanding the response

Every MCP response from Traverse includes a standard content block for the MCP client, plus a _traverse object with execution metadata.

content

Array of MCP content blocks. Usually a single text block with the capability output. Passed directly to the AI agent.

_traverse.trace_id

Unique ID for this execution. Use it to look up the full trace record for debugging.

_traverse.status

completed or error. If error, an error field is also present with the reason and failing state.

_traverse.duration_ms

Total wall time for the execution in milliseconds.

_traverse.capability

The ID and version of the capability that was selected and executed.

_traverse.events_emitted

List of event IDs published during execution. Empty array if no events were emitted.

Claude Desktop

Connect to Claude Desktop or other MCP clients

Claude Desktop uses a claude_desktop_config.json file. The pattern is the same as the generic config above. Add a traverse entry under mcpServers.

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "traverse": {
      "command": "/absolute/path/to/traverse/target/debug/traverse-mcp",
      "args": []
    }
  }
}
        

Restart Claude Desktop after editing the config. The Traverse capabilities will appear in the tools list. You can ask Claude to use them by name or just describe the goal in natural language.

Path must be absolute. Relative paths do not work in Claude Desktop config. Use the full path from your filesystem root.

Next steps

Architecture

Understand how the runtime processes requests and what the trace contains.

MCP Troubleshooting

Server not responding? Common fixes for stdio connection issues.