graphql

This MCP server dynamically builds tools for a GraphQL API by introspecting the endpoint's schema. On startup it connects to the configured GraphQL endpoint, performs an introspection query, and generates MCP tools for each query and mutation found in the schema. The exposure of these tools is controlled by an exposed.yaml file: by default, all discovered functions are added as enabled, and only those marked true are registered as MCP tools. You can also gradually curate the set of exposed functions, enable new ones automatically, and have functions removed if they no longer exist in the schema. Tools are named with a prefix convention: query_<name> for GraphQL queries and mutation_<name> for GraphQL mutations. When you call a tool, the server constructs the corresponding GraphQL operation with variables and executes it against the endpoint, returning the results as formatted JSON.

To use the server, supply the GraphQL endpoint (and optional Bearer token) via environment variables or command line arguments. If you enable HTTP transport, you can secure the MCP API with an AUTH_TOKEN and call tools via the /mcp endpoint using JSON-RPC requests such as tools/list or tools/call for a specific query tool. The exposed tools can also be integrated with Claude Desktop or other MCP clients by configuring the command, arguments, and environment variables as shown in the example configuration.

Key capabilities include automatic tool generation from the schema, type-safe variable handling, automatic query generation with smart field selection, and robust error handling and validation. Bearer token authentication can be enabled to protect the HTTP endpoint, and exposed.yaml provides a flexible, declarative way to manage which GraphQL operations are accessible as MCP tools.

Prerequisites

• Node.js (recommended LTS version, e.g., 16+)
• npm (comes with Node.js)
• Access to the GraphQL endpoint you intend to introspect

1. Clone or download the MCP server repository for GraphQL
2. Install dependencies

npm install

3. Configure environment variables or provide command line arguments (examples below)

• GRAPHQL_URL: GraphQL endpoint URL
• GRAPHQL_TOKEN: Optional Bearer token for GraphQL authentication
• AUTH_TOKEN: Optional MCP server authentication token (HTTP transport)

4. Run the server (STDIO transport by default)

# via environment variables
export GRAPHQL_URL="https://api.example.com/graphql"
export GRAPHQL_TOKEN="your-bearer-token"
node src/index.js

# or via command-line options
node src/index.js --graphql-url "https://api.example.com/graphql" --token "your-bearer-token"

5. (Optional) Enable HTTP transport for remote access

export GRAPHQL_URL="https://api.example.com/graphql"
export GRAPHQL_TOKEN="your-bearer-token"
export AUTH_TOKEN="your-mcp-secret-token" 
node src/index.js --transport http --port 3000

6. Initialize or edit exposed.yaml to control which GraphQL operations are exposed as MCP tools. On first run, the server will create the file and gradually keep it in sync with the schema.

Tips and common considerations:

• Exposed functionality is driven by exposed.yaml. If a function is set to false, it will not be registered as an MCP tool, even if present in the GraphQL schema.
• New GraphQL fields discovered in the schema are automatically added to exposed.yaml with a default true value, enabling quick onboarding of new tools.
• When using HTTP transport, you can enforce authentication by setting AUTH_TOKEN. Requests without a valid token will be rejected with 401 Unauthorized.
• The tool naming convention uses query_<name> for queries and mutation_<name> for mutations. You can customize tool invocation with query and mutation prefixes and, depending on the implementation, potential argument shaping or field selection.
• Bearer token handling can be done via GRAPHQL_TOKEN for the GraphQL API and AUTH_TOKEN for MCP authentication. URLs and tokens can be provided in environment variables or as CLI arguments.
• If the GraphQL API requires complex authentication (e.g., additional headers), you may need to modify or extend the server to pass those headers through during GraphQL requests.