multi-graphql-mcp

Enhanced fork of mcp-graphql with multi-endpoint support and LLM context optimization.

What's New (v3.0)

• Multi-endpoint: Single MCP instance connects to multiple GraphQL APIs
• Schema summary: Compact summaries instead of full SDL in LLM context
• Response offloading: Large responses written to file, summary returned inline
• CSV export: Query results as CSV for data analysis
• Pagination: Application-level max_rows truncation
• Pagination guidance: Tool descriptions hint LLMs to use first/skip to avoid timeouts

Install

npx -y multi-graphql-mcp

Quick Start

Single endpoint (backward compatible)

{
  "mcpServers": {
    "graphql": {
      "command": "npx",
      "args": ["-y", "multi-graphql-mcp"],
      "env": {
        "ENDPOINT": "http://localhost:3000/graphql"
      }
    }
  }
}

Multi-endpoint

Create a config file (e.g. graphql-endpoints.config.json):

{
  "endpoints": [
    {
      "name": "orders",
      "url": "https://api.example.com/orders/graphql",
      "headers": { "Authorization": "Bearer xxx" }
    },
    {
      "name": "users",
      "url": "https://api.example.com/users/graphql"
    }
  ],
  "responseSizeThreshold": 2048,
  "outputDir": "/tmp/mcp-graphql/",
  "defaultEndpoint": "orders"
}

{
  "mcpServers": {
    "graphql": {
      "command": "npx",
      "args": ["-y", "multi-graphql-mcp"],
      "env": {
        "MCP_GRAPHQL_CONFIG": "/path/to/graphql-endpoints.config.json"
      }
    }
  }
}

Environment Variables

Variable	Description	Default
ENDPOINT	GraphQL endpoint URL (single-endpoint mode)	http://localhost:4000/graphql
HEADERS	JSON string of request headers	{}
ALLOW_MUTATIONS	Enable mutation operations	false
NAME	MCP server name	mcp-graphql
SCHEMA	Path/URL to schema file (skip introspection)	-
MCP_GRAPHQL_CONFIG	Path to multi-endpoint config file	-
RESPONSE_SIZE_THRESHOLD	Bytes before offloading to file	2048
MCP_GRAPHQL_OUTPUT_DIR	Directory for output files	/tmp/mcp-graphql/

Tools

introspect-schema

Introspect the GraphQL schema with context-aware detail levels.

Parameter	Type	Default	Description
endpoint	string	default	Endpoint name to introspect
detail	summary | full | types	summary	Detail level
types	string[]	-	Type names (when detail=types)

Summary mode (default) returns compact markdown with type/field counts and root query fields. Full SDL is always written to file for reference. TIP: Check Query fields for pagination args (first, skip, after, orderBy) to plan efficient queries.

query-graphql

Execute GraphQL queries with export and pagination support.

Parameter	Type	Default	Description
query	string	required	GraphQL query
variables	string	-	JSON variables
endpoint	string	default	Endpoint name
output_format	json | csv	json	Output format
max_rows	number	-	Truncate results

Large JSON responses are automatically written to file with an inline summary. CSV output is always written to file.

Important: Always use pagination (first/skip or first/after) in your GraphQL queries to avoid timeouts on large datasets. Start with small page sizes (first: 10-50) and increase only if needed.

Config File Format

{
  "endpoints": [
    {
      "name": "my-api",           // Endpoint identifier
      "url": "https://...",       // GraphQL URL (required)
      "headers": {},              // Request headers
      "allowMutations": false,    // Enable mutations
      "schema": "./schema.graphql" // Optional local/remote schema
    }
  ],
  "responseSizeThreshold": 2048,  // Bytes before file offload
  "outputDir": "/tmp/mcp-graphql/", // Output directory
  "defaultEndpoint": "my-api"     // Default endpoint name
}

Security

Mutations are disabled by default per-endpoint. Enable with "allowMutations": true in endpoint config or ALLOW_MUTATIONS=true env var.

License

MIT