Experimental PoC

graphql-mcp

An MCP (Model Context Protocol) server that exposes GraphQL operations as tools for AI models. Point it at any GraphQL endpoint and a schema, and it turns your operations into typed MCP tools — with schema exploration tools, hot reload, OAuth resource-server auth, MCP prompts, MCP Apps widgets, and OpenTelemetry built in.

Configuration is plain TypeScript — no YAML, no env-var templating; read process.env directly in your config file.

Quick start

npm install graphql-mcp   # or pnpm add / vp add

Create graphql-mcp.config.ts:

import { defineConfig } from "graphql-mcp";

export default defineConfig({
  endpoint: "http://localhost:4000/graphql",
  schema: { source: "local", path: "./schema.graphql" },
  operations: { source: "local", paths: ["./operations"] },
  tools: {
    introspect: { enabled: true },
    search: { enabled: true },
    validate: { enabled: true },
    execute: { enabled: true },
  },
});

Run it:

graphql-mcp                     # stdio transport (default)
graphql-mcp path/to/config.ts   # explicit config path

Local schema files, operation files, prompt files, and the config file itself are watched: edits hot reload without dropping connected sessions (config changes trigger a validated in-process restart; SIGHUP forces one).

Related MCP server: mcp4gql

How operations become tools

Every named GraphQL operation in your operation files becomes one MCP tool:

• The tool name is the operation name; leading # comments become the tool description (otherwise one is generated from schema descriptions plus the tree-shaken SDL of the types the operation touches).

• The input schema is derived from the operation's variables (non-null variables are required; input objects, enums, lists, and custom scalars are fully expanded). # comments before individual variables override their descriptions.

• Queries are annotated read-only and idempotent; mutations destructive. Mutations are skipped unless overrides.mutationMode is explicit or all.

• Fields marked @private are stripped from the query sent downstream and filtered out of the structured result the model sees (the full response is preserved in _meta.structuredContent for the host client).

Operation sources: local (watched .graphql files/directories), manifest (a local apollo-persisted-query-manifest v1 JSON file), or none.

Schema tools

Four individually toggleable tools under tools:

Each accepts an optional hint appended to its description.

Transports

• stdio (default) — for local MCP clients.

• http — streamable HTTP on /mcp with per-session state (or stateless via statefulMode: false), CORS, Host/Origin validation against DNS rebinding, a /health endpoint (?live / ?ready), and graceful shutdown.

OAuth 2.1 resource server

Nest auth under the HTTP transport to require bearer tokens:

transport: {
  type: "http",
  port: 8000,
  auth: {
    servers: ["https://auth.example.com"], // OIDC/OAuth discovery + JWKS
    audiences: ["my-api"],
    scopes: ["read:graphql"],
    scopeMode: "require_all",
  },
},
overrides: {
  requiredScopes: { DeleteUser: ["admin"] }, // per-operation step-up
},

The server publishes RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource, answers challenges with WWW-Authenticate (including insufficient_scope), and passes validated tokens through to the GraphQL endpoint (disable with disableAuthTokenPassthrough).

Prompts and MCP Apps

• prompts: { directory: "./prompts" } serves Markdown files with YAML frontmatter (name, description, arguments) as MCP prompts, with {{arg}} substitution and hot reload.

• apps: { directory: "./apps" } serves MCP Apps: each subdirectory with an .application-manifest.json contributes a ui://widget/... HTML resource and entrypoint tools backed by GraphQL operations, including prefetch operations, extra inputs/outputs, CSP and widget settings, and OpenAI-Apps-SDK/MCP-Apps targeting via ?appTarget= or client capabilities.

Telemetry

telemetry: {
  serviceName: "my-graphql-mcp",
  exporters: {
    metrics: { otlp: { protocol: "http/protobuf" } },
    tracing: { otlp: { endpoint: "http://collector:4318/v1/traces" } },
  },
},

Emits graphql_mcp.operation.count / graphql_mcp.operation.duration metrics and per-tool-call spans, with configurable attribute omission, export interval, and sampler.

Config reference

Top-level keys (all optional except schema):

The config is validated with helpful errors; unknown keys are rejected. See examples/graphql-mcp.config.ts for a commented full example.

Development

vp install   # install dependencies
vp check     # format, lint, type check
vp test      # run the test suite
vp pack      # build dist/ (library + CLI)

Acknowledgements

The behavior of this server is a TypeScript reimplementation inspired by the MIT-licensed Apollo MCP Server (Rust), excluding its GraphOS-specific functionality.

License

MIT