MCP Server: GraphQL Schema Explorer for LLMs

Overview

MCP Server: GraphQL Schema Explorer implements a Model Context Protocol (MCP) endpoint that exposes GraphQL schema information as discoverable resources. Instead of embedding entire GraphQL schemas into an LLM prompt, the server lets an LLM request just the parts it needs — types, fields, arguments, docs — on demand. That reduces context size and keeps LLM reasoning focused and up to date with the live schema.

The server performs standard GraphQL introspection, organizes the results into MCP-style resources, and serves them over HTTP. Clients (including LLM-driven agents) can browse, search, and fetch structured schema fragments programmatically, making it straightforward to build tools for query generation, validation, or documentation that work with very large schemas.

Features

• Exposes GraphQL schema metadata (types, fields, args, enums, directives) as MCP resources
• On-demand introspection: fetch only the parts an LLM needs to avoid context bloat
• Caching and pagination for large schemas
• Simple HTTP API that fits MCP-style resource discovery/workflows
• Support for protecting upstream GraphQL endpoints via custom headers or env-configured auth
• Example clients and usage patterns for LLM agents and developer tooling

Installation / Configuration

Prerequisites:

• Node.js 18+ (or compatible runtime)
• Access to a GraphQL endpoint that allows introspection (or an introspection JSON file)

Clone and install:

git clone https://github.com/hannesj/mcp-graphql-schema.git
cd mcp-graphql-schema
npm install

Environment configuration Create a .env file or export environment variables. Common variables:

GRAPHQL_ENDPOINT=https://api.example.com/graphql
GRAPHQL_AUTH_HEADER="Bearer xxxxx"
PORT=3000
CACHE_TTL_SECONDS=300

Run the server locally:

# development
npm run dev

# production
npm start

Docker Build and run with Docker:

docker build -t mcp-graphql-schema .
docker run -e GRAPHQL_ENDPOINT=https://api.example.com/graphql -p 3000:3000 mcp-graphql-schema

Available Resources

The server exposes resource types that represent the standard pieces of a GraphQL schema. Example endpoints and the resource purpose:

Note: exact URL patterns may vary depending on deployment; consult the running server’s root resources endpoint to discover concrete paths.

Available operations typically include:

• List and paginate resources
• Fetch detailed resource representations (JSON)
• Search by name/description
• Optionally supply authentication headers for the upstream GraphQL endpoint

Usage Examples

1. List top-level resources:

curl http://localhost:3000/resources

2. Get a type’s shape and fields:

curl http://localhost:3000/resources/types/User
# or if using resource id pattern
curl http://localhost:3000/resources/types/Query_user

3. Fetch a specific field’s arguments and return type:

curl http://localhost:3000/resources/types/User/fields/friends

4. Use from a program (Node.js example):

import fetch from 'node-fetch';

const base = 'http://localhost:3000';
const res = await fetch(`${base}/resources/types/Post`);
const postType = await res.json();
console.log(postType.fields);

5. Integrating with an LLM workflow

• Prompt the model to decide what schema piece it needs (e.g., “Which fields exist on Post?”).
• Call the MCP server to fetch that resource.
• Provide the fetched JSON fragment to the LLM as context (much smaller than the whole schema).
• Ask the model to generate or validate a GraphQL operation.

Use Cases

• LLM-powered query generation: Let the model fetch only the type and field metadata required to construct a valid query for a particular intent.
• Schema-aware autocomplete: IDEs and agents can provide precise completion by requesting field and arg metadata on demand.
• Documentation tooling: Generate examples and API docs from live schema fragments without pulling the full schema into memory.
• Validation and linting: Validate generated queries by fetching return types and field requirements before execution.
• Multi-tenant or very large schemas: Keep agent context small when working with schemas that exceed prompt size limits.

Notes for Developers

• Ensure the upstream GraphQL endpoint allows introspection or provide a precomputed introspection JSON.
• Use caching (CACHE_TTL_SECONDS) to balance freshness against request volume.
• The server is intended to be a mechanical interface for model-context retrieval; it doesn’t author queries for you. Combine it with an LLM orchestration layer or agent that issues MCP requests when it needs schema facts.
• Check the server’s root resources endpoint after startup to discover runtime paths and any authentication requirements.

If you need a custom slice of metadata, consider extending the server’s resource mappers to include additional fields (comments, deprecation reasons, examples) so downstream LLMs get exactly the context they need.