GraphQL MCP Server: Automatically Expose Queries as Tools

Overview

GraphQL MCP Server automatically exposes a GraphQL API as a set of Model Context Protocol (MCP) tools. It introspects a GraphQL endpoint, converts operations (queries and mutations) into individual tool descriptors with typed inputs/outputs, and serves them through a lightweight MCP-compatible HTTP server. The result is a developer-friendly bridge: large language models and agent frameworks can call GraphQL operations as if they were ordinary tools or functions without custom glue code.

This approach reduces friction for integrating backend APIs into automated workflows. Instead of hand-writing adapters for each GraphQL operation, you get discoverable, validated tool definitions generated from the live schema. That makes it easier to build reliable automation, prototypes, and AI agents that need precise access to business data exposed via GraphQL.

Features

• Automatic schema introspection from any GraphQL endpoint
• Per-operation tool generation (queries and mutations)
• Typed argument schemas derived from GraphQL input types
• Optional allowlist/denylist to control which operations are exposed
• Support for passing custom headers (auth tokens, tracing headers)
• Simple CLI, Docker, or library modes for embedding in other tools
• JSON-based tool invocation with input validation
• Minimal dependencies and a small runtime footprint

Installation / Configuration

Install with pip (recommended) or run via Docker. Replace URL/config values as needed.

Install from PyPI:

pip install mcp_graphql

Run via CLI:

mcp-graphql --graphql-url https://api.example.com/graphql --port 8080

Docker:

docker run --rm -p 8080:8080 \
  -e GRAPHQL_URL=https://api.example.com/graphql \
  ghcr.io/drestrepom/mcp_graphql:latest

Example environment variables and a JSON/YAML configuration:

# config.yml
graphql_url: "https://api.example.com/graphql"
port: 8080
introspection_headers:
  Authorization: "Bearer YOUR_TOKEN"
allowlist:
  - Query.getUser
  - Query.listProducts
denylist:
  - Mutation.deleteUser

CLI flags:

mcp-graphql --graphql-url https://api.example.com/graphql \
            --port 8080 \
            --introspection-header "Authorization: Bearer TOKEN" \
            --allow "Query.getUser" --allow "Query.listProducts"

Configuration options (summary):

Available Tools / Resources

After startup the server exposes one tool per GraphQL operation. Each tool includes:

• name: a stable name derived from operation type and field (e.g., Query.getUser)
• description: GraphQL field description (when available)
• inputs: a JSON schema-like description of required/optional arguments
• execution endpoint: POST /tool/ or a unified /invoke endpoint

  Sample generated tool descriptor (simplified):

  {
    "name": "Query.getUser",
    "description": "Fetch a user by ID",
    "inputs": {
      "type": "object",
      "properties": {
        "id": {"type": "string"}
      },
      "required": ["id"]
    }
  }
  

  Invoking the tool (HTTP):

  curl -X POST "http://localhost:8080/tool/Query.getUser" \
    -H "Content-Type: application/json" \
    -d '{"id":"user-123"}'
  # -> JSON response with the GraphQL result data
  

  Internally the server maps tool inputs into GraphQL variables and runs the corresponding query against the upstream endpoint, returning the data payload or structured error information.

  Use Cases

  • LLM-enabled agents: Allow an agent to perform GraphQL reads/writes by calling discrete tools (e.g., Query.getOrder, Mutation.createInvoice) rather than embedding raw GraphQL text in prompts.
  • Rapid prototyping: Expose a new GraphQL service to conversational interfaces or automation platforms without writing operation-specific glue code.
  • Secure, controlled access: Use allowlists and request headers to limit which operations are callable and to inject service credentials at runtime.
  • Data-driven actions: Chain multiple generated tools in workflows (fetch user -> list user orders -> create shipment) while preserving input validation and predictable outputs.
  • Observability & testing: The MCP layer provides a clear surface for mocking or logging tool calls in integration tests or agent simulators.

  Concrete example: Exposing a product catalog

  1. Introspect a GraphQL API that defines Query.product(id: ID!): Product and Query.searchProducts(term: String): [Product].
  2. The server generates Query.product and Query.searchProducts tools.
  3. An automation calls Query.searchProducts with {“term”:“headphones”} to get product IDs, then calls Query.product for each ID to fetch details and generate a report.

  Links

  • GitHub repository: https://github.com/drestrepom/mcp_graphql
  Tags:api-integration