Private Subgraph MCP Server

A Model Context Protocol (MCP) server that allows LLMs to interact with privately hosted subgraphs through a configurable registry.

Features

• Registry-based Discovery: Manage your private subgraphs through a configurable JSON registry
• Schema Introspection: Get GraphQL schemas for any configured subgraph
• Query Execution: Execute GraphQL queries against your private subgraphs
• Flexible Authentication: Support for various auth methods (API keys, bearer tokens)
• Search Functionality: Find subgraphs by keyword in names and descriptions
• Multiple Deployment Modes: STDIO mode for direct MCP integration or SSE (Server-Sent Events) for HTTP access
• Prometheus Metrics: Built-in observability for monitoring tool usage

Usage

The private-subgraph-mcp server allows you to interact with your privately hosted subgraphs through a configurable registry.

Requirements

• Rust (latest stable version recommended: 1.75+)
• A JSON configuration file listing your private subgraphs
• Access to your private subgraph endpoints

Installation

# Clone the repository
git clone [email protected]:graphops/subgraph-mcp.git
cd subgraph-mcp

# Build the project
cargo build --release

Configuration

1. Create your subgraph registry: Copy the example configuration and customize it for your subgraphs:

cp subgraphs.example.json subgraphs.json

2. Configure your subgraphs: Edit subgraphs.json with your private subgraph details:

[
  {
    "id": "my-protocol",
    "name": "My DeFi Protocol", 
    "url": "https://your-graph-node.example.com/subgraphs/name/my-protocol",
    "description": "My custom DeFi protocol subgraph",
    "chain": "mainnet",
    "auth_header": "Bearer your-api-key-here"
  }
]

3. MCP Client Configuration: Add the following to your MCP client configuration (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "private-subgraph-mcp": {
      "command": "/path/to/your/subgraph-mcp/target/release/subgraph-mcp",
      "env": {
        "SUBGRAPH_CONFIG_PATH": "/path/to/your/subgraphs.json"
      }
    }
  }
}

Replace /path/to/your/subgraph-mcp with the absolute path to your compiled binary and /path/to/your/subgraphs.json with the path to your configuration file.

Running the Server

STDIO Mode (recommended for MCP clients):

cargo run

SSE Mode (for HTTP access with metrics):

cargo run -- --sse

Environment Variables

• SUBGRAPH_CONFIG_PATH: Path to your subgraphs.json configuration file (default: subgraphs.json)
• SUBGRAPH_REQUEST_TIMEOUT_SECONDS: HTTP request timeout in seconds (default: 120)
• HOST/PORT: SSE server bind address (default: 0.0.0.0:8000)
• METRICS_HOST/METRICS_PORT: Metrics server address (default: 0.0.0.0:9091)

Available Tools

The server exposes the following tools for interacting with your private subgraphs:

• list_subgraphs: List all subgraphs configured in your registry with their IDs, names, and descriptions.
• search_subgraphs_by_keyword: Search for subgraphs by keyword in their names and descriptions.
• get_schema_by_id: Get the GraphQL schema for a subgraph using its configured ID.
• execute_query_by_id: Execute a GraphQL query against a subgraph using its configured ID.
• get_schema_by_subgraph_id: (DEPRECATED) Legacy method - use get_schema_by_id instead.

Natural Language Queries

Once connected to an LLM with this MCP server, you can ask natural language questions about your private subgraphs.

Important: Claude Desktop may not automatically utilize server resources. To ensure proper functionality, manually add Private Subgraph Server Instructions resource to your chat context by clicking on the context menu and adding the resource.

Example usage in Claude (or other MCP clients), assuming you added the resource to your prompt:

User: Show me the latest swaps from my Uniswap V3 subgraph.
Assistant: I'll search for Uniswap V3 subgraphs in your registry, get the schema, and execute a query for recent swaps.

1. First, I search for "uniswap" in your configured subgraphs
2. I get the GraphQL schema to understand the available entities  
3. I execute a GraphQL query to fetch the latest swaps

This workflow allows you to interact naturally with your private subgraphs without needing to know the exact GraphQL syntax.

The LLM will automatically:

1. Use search_subgraphs_by_keyword or list_subgraphs to find your configured subgraphs
2. Use get_schema_by_id to understand the GraphQL schema structure
3. Generate and execute appropriate GraphQL queries using execute_query_by_id
4. Present the results in a readable format

Configuration Examples

Example subgraphs.json

See subgraphs.example.json for a complete configuration example with different authentication methods and hosting providers.

Monitoring

When running in SSE mode, Prometheus metrics are available at:

• Endpoint: /metrics
• Default URL: http://localhost:9091/metrics

Available Metrics

• mcp_tool_calls_total{tool_name, status}: Counter for MCP tool calls
• mcp_tool_call_duration_seconds{tool_name}: Histogram of tool call durations
• gateway_requests_total{endpoint_type, status}: Counter for HTTP requests to subgraphs
• gateway_request_duration_seconds{endpoint_type}: Histogram of request durations

Troubleshooting

Common Issues

• "Subgraph not found": Verify your subgraphs.json configuration and that SUBGRAPH_CONFIG_PATH points to the correct file
• "HTTP timeout": Increase SUBGRAPH_REQUEST_TIMEOUT_SECONDS for complex queries
• "Authentication failed": Check your auth_header configuration and API key validity
• "Connection refused": Verify your subgraph URLs are accessible and correct

Configuration Validation

Test your configuration by running:

cargo run -- list_subgraphs

This will show all configured subgraphs and help identify configuration issues.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Apache-2.0