MCP Server

Traverse includes a built-in Model Context Protocol (MCP) server, allowing AI assistants to query and explore your graph databases directly.

Overview

MCP is an open protocol by Anthropic that enables AI models to interact with external tools and data sources. Traverse implements the Streamable HTTP transport (JSON-RPC 2.0 over HTTP POST), exposing six tools for graph database operations.

Protocol version: 2025-11-25

Quick Start

Example: Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "traverse": {
      "url": "http://localhost:7691/api/mcp",
      "headers": {
        "Authorization": "Bearer tvs_your_api_key"
      }
    }
  }
}

Replace tvs_your_api_key with the API key shown in the server startup banner. Once configured, Claude can query your graph databases, explore schemas, find nodes, and traverse relationships.

Any MCP Client

Any MCP-compatible client can connect using the Streamable HTTP transport. The endpoint URL is http://<host>:<port>/api/mcp and requires the same API key authentication as the HTTP API.

Authentication

The MCP endpoint uses the same API key authentication as all other /api/* endpoints. Pass the key via:

• Authorization: Bearer tvs_... header (recommended)
• X-API-Key: tvs_... header

Available Tools

All tools accept an optional database argument. If omitted, the server's default database is used.

Tool Details

query

Execute any Cypher query. Supports parameterized queries for safe value injection.

{
  "name": "query",
  "arguments": {
    "cypher": "MATCH (p:Person) WHERE p.age > $minAge RETURN p.name, p.age ORDER BY p.age DESC",
    "parameters": {"minAge": 30},
    "database": "mydb"
  }
}

Returns columns, rows, total row count, truncation flag, and execution time.

schema

Inspect the database structure without writing any queries.

{
  "name": "schema",
  "arguments": {"database": "mydb"}
}

Returns labels with their properties and types, relationship types with properties, indexes, and constraints.

databases

Discover what databases are available on the server.

{
  "name": "databases",
  "arguments": {}
}

search_nodes

Find nodes without writing a full Cypher query.

{
  "name": "search_nodes",
  "arguments": {
    "label": "Person",
    "property": "name",
    "value": "Alice"
  }
}

shortest_path

Find the shortest path between two nodes. Use max_depth to limit traversal (default: 10).

{
  "name": "shortest_path",
  "arguments": {
    "from_id": 42,
    "to_id": 99,
    "max_depth": 5
  }
}

neighbors

Explore the neighborhood of a node. Filter by direction (outgoing, incoming, both) and edge_type.

{
  "name": "neighbors",
  "arguments": {
    "node_id": 42,
    "direction": "outgoing",
    "edge_type": "KNOWS",
    "limit": 20
  }
}

Protocol Reference

Initialize

The MCP handshake must be the first message. The server responds with its capabilities and version.

POST /api/mcp
Content-Type: application/json
Authorization: Bearer tvs_...

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "my-app", "version": "1.0"}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {"tools": {}},
    "serverInfo": {"name": "traverse", "version": "0.5.0"}
  }
}

List Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Call a Tool

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "cypher": "MATCH (n) RETURN labels(n) AS label, count(*) AS count"
    }
  }
}

Successful tool results:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "{\"columns\": [...], \"rows\": [...]}"}]
  }
}

Tool errors (query syntax errors, database not found, etc.):

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "Query error: ..."}],
    "isError": true
  }
}

Ping

{"jsonrpc": "2.0", "id": 4, "method": "ping", "params": {}}

Notifications

Notifications (e.g. notifications/initialized) return 202 Accepted with no body, per the MCP spec.

Transport Details

Error Codes

Standard JSON-RPC 2.0 error codes:

Tool-level errors (bad query, database not found, etc.) are returned as successful JSON-RPC responses with isError: true in the result, following the MCP convention.