GraphQL MCP Server
The GraphQL MCP Server enables AI agents to connect to any GraphQL endpoint, introspect its schema, and execute queries and mutations. Key capabilities include:
Connection & Configuration
Connect to any GraphQL endpoint, with configurable request timeouts
Authenticate via Bearer tokens, HTTP Basic auth (username/password), or custom HTTP headers (add, remove, or replace)
Check connection status — including endpoint config, masked secrets, auth state, and schema cache — with an optional live ping to verify reachability
Schema Introspection & Exploration
Fetch and cache the full GraphQL schema via introspection
List all types with filtering by kind (OBJECT, SCALAR, ENUM, etc.) or name substring
Describe any type in detail — fields, arguments, return types, interfaces, enum values, and input fields
List root query, mutation, and subscription fields (subscriptions are informational only; not executable over HTTP)
Describe individual fields including arguments, deprecation info, and return types
Search the entire schema for types, fields, input fields, and enum values by substring
Query & Mutation Execution
Execute raw GraphQL query or mutation strings with optional variables and operation names
Execute queries or mutations by field name only — the server automatically constructs the GraphQL string and selection set
Cache Management
Retrieve the cached schema as JSON for bulk inspection
Clear the schema cache for a specific endpoint or all endpoints
Force a fresh schema reload when the remote schema may have changed
Reliability
Automatic retries with backoff for transient errors
Output sanitization to prevent prompt injection
Connects to any GraphQL endpoint, providing tools to introspect schemas, execute queries and mutations, search types and fields, and manage connections with authentication and caching.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GraphQL MCP Server introspect the schema at https://api.example.com/graphql"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GraphQL MCP Server
MCP server for GraphQL — schema introspection, auto-generated tools, query/mutation execution for Claude, Cursor, and AI agents.
What It Does
Connects to any GraphQL endpoint and gives AI agents the ability to:
Introspect schemas — discover all types, queries, mutations, and subscriptions
Execute queries and mutations — raw GraphQL strings or typed field-based calls
Search and explore — find types, fields, and arguments across the schema
Manage connections — switch endpoints, configure auth, cache schemas
Related MCP server: mcp-graphql-tools
Quick Start
npx @supernova123/graphql-mcp-serverSet your endpoint via environment variable:
GRAPHQL_ENDPOINT=https://your-api.com/graphql npx @supernova123/graphql-mcp-serverOr configure at runtime with the connect_endpoint tool.
Tools (20)
Connection & Configuration
Tool | Description |
| Set or change the active GraphQL endpoint |
| Configure Bearer token authentication |
| Configure HTTP Basic authentication |
| Replace custom HTTP headers |
| Add/update a single header |
| Remove a header |
| Show endpoint config, auth state, and schema cache |
Schema Introspection
Tool | Description |
| Fetch the full schema via introspection |
| List all types (filter by kind or name) |
| Get full details of a single type |
| List all root query fields |
| List all root mutation fields |
| List all root subscription fields |
| Get full details of a field |
| Search types and fields by substring |
Execution
Tool | Description |
| Send a raw GraphQL query |
| Send a raw GraphQL mutation |
| Execute a query by field name (auto-constructed) |
| Execute a mutation by field name (auto-constructed) |
Cache Management
Tool | Description |
| Return the cached introspection result |
| Clear schema cache |
| Force a fresh introspection |
Environment Variables
Variable | Description | Default |
| GraphQL endpoint URL | (none — must configure at runtime) |
| Bearer token for Authorization header | (none) |
| Basic auth username | (none) |
| Basic auth password | (none) |
| Request timeout in milliseconds | 30000 |
| Custom headers (e.g. | (none) |
Configuration (Claude Desktop)
{
"mcpServers": {
"graphql": {
"command": "npx",
"args": ["-y", "@supernova123/graphql-mcp-server"],
"env": {
"GRAPHQL_ENDPOINT": "https://your-api.com/graphql",
"GRAPHQL_AUTH_TOKEN": "***"
}
}
}
}Features
No external GraphQL library — minimal dependency surface, works at the HTTP layer
Schema caching — introspect once, reuse across tool calls
Retry with backoff — transient errors (5xx, 429, timeouts) are retried automatically
Output sanitization — ANSI stripping and length capping prevent prompt injection
Type-safe — TypeScript with Zod validation on all tool inputs
Auth flexibility — Bearer tokens, Basic auth, or arbitrary HTTP headers
Development
npm install
npm run build
npm testBlog Posts
Real data from building and running this server:
What 6,000 npm Downloads Taught Me — distribution and growth data
The MCP Server Naming Playbook — how naming affects discoverability
License
MIT
Available Tools
22 toolsadd_headerAIdempotent
Add or update a single custom HTTP header without replacing the others. Useful for one-off headers like X-Trace-Id. To remove, use remove_header.
Inputs: key (required), value (required).
clear_cacheAIdempotent
Clear the schema cache. If endpoint is given, clears only that endpoint's cache; otherwise clears all. Use this to free memory after switching endpoints, or to force a fresh introspection on the next call.
Inputs: endpoint.
connect_endpointAIdempotent
Set or change the active GraphQL endpoint. All subsequent tool calls (introspect, query, mutate) target this endpoint. Replaces the previous client; existing schema cache for the old endpoint is kept but a new schema will be fetched for the new one. Use set_auth_token / set_headers immediately after to configure credentials. If the endpoint requires CORS for browser access, that is the caller's responsibility — the MCP server is a backend process.
Inputs: endpoint (required), timeout_ms.
describe_fieldARead-onlyIdempotent
Get full details of a single field on any type: description, return type, arguments (each with name, type, description, default value), and deprecation info. Pass type_name='Query' or 'Mutation' to look up root operations, or pass any object type name to look up one of its fields.
Inputs: type_name (required), field_name (required).
describe_typeARead-onlyIdempotent
Get full details of a single type: all fields (with their args and return types), input fields, interfaces, enum values, and possible types. Use this to understand a type's shape before constructing a query. Pass the name of any type — including root types like 'Query' or 'Mutation', input types like 'CreateUserInput', or scalar types.
Inputs: type_name (required), include_deprecated.
execute_mutationA
Send a raw GraphQL mutation string to the endpoint. Functionally identical to execute_query — use whichever is more semantically clear. Not idempotent: mutations can have side effects.
Inputs: mutation (required), variables, operation_name.
execute_queryARead-onlyIdempotent
Send a raw GraphQL query string to the endpoint. Use this when you already have a complete query — for example, one written by a human or copied from API docs. Returns the data field of the response, or a structured error message if the server returned errors. Variables are passed through as-is. Idempotent: same query → same result (for read-only queries).
Inputs: query (required), variables, operation_name.
execute_typed_mutationA
Execute a mutation by field name. Looks up the field on the root Mutation type, validates arguments, and constructs the mutation. If selection is omitted, defaults to __typename. Not idempotent — mutations can have side effects.
Inputs: field (required), variables, selection.
execute_typed_queryARead-onlyIdempotent
Execute a query by field name. Looks up the field on the root Query type using the introspected schema, validates that the variables you pass match the field's argument types (by name), and constructs a query string automatically. If you don't provide a selection set, the server auto-builds one with __typename plus scalar fields. Requires the schema to be introspected first.
Inputs: field (required), variables, selection, include_deprecated.
get_cached_schemaARead-onlyIdempotent
Return the cached introspection result for the current endpoint as JSON. Use this when you need the full schema in one shot (e.g. to build a query offline). For large schemas this can be 1MB+ — use describe_type / list_queries / search_schema for targeted access. The max_depth parameter caps type traversal to keep output size bounded.
Inputs: include_system_types, max_depth.
get_connection_statusARead-onlyIdempotent
Show the current endpoint, configured headers (with secrets masked), auth state, and schema cache state. Set ping=true to also send a {__typename} query to verify the endpoint is reachable and measure latency.
Inputs: ping.
introspect_schemaARead-onlyIdempotent
Fetch the full GraphQL schema via introspection and cache it. Required before any list_*, describe_*, or execute_typed_* call. Idempotent: returns the cached schema if available unless force=true. The schema can be large (>1MB for Shopify/GitHub) so consider clearing the cache or using search/describe tools on subsequent calls.
Inputs: force.
list_mutationsARead-onlyIdempotent
List all root mutation fields (e.g. createUser, updatePost). Each entry shows the return type and argument types. Returns an empty list if the schema has no mutation type. Use search= to filter by name.
Inputs: search, limit.
list_queriesARead-onlyIdempotent
List all root query fields (e.g. user, posts, search). Each entry shows the field's return type and its argument types. Use describe_field to get more detail on a specific query. Use search= to filter by name substring.
Inputs: search, limit.
list_subscriptionsARead-onlyIdempotent
List all root subscription fields (e.g. messageAdded, onUserUpdate). Note: this MCP server uses HTTP request/response, so subscriptions cannot be executed here — list is informational only. Use a websocket-based GraphQL client to consume subscriptions. Returns an empty list if the schema has no subscription type.
Inputs: search, limit.
list_typesARead-onlyIdempotent
List all types in the introspected schema. Filter by kind (OBJECT, SCALAR, INTERFACE, UNION, ENUM, INPUT_OBJECT) or by name substring. Excludes introspection system types (those starting with __) by default. Use describe_type to get full details for a specific type.
Inputs: kind, search, limit.
reload_schemaAIdempotent
Force a fresh introspection, replacing any cached schema for the given endpoint (or the current one if not specified). Use this when you suspect the remote schema has changed.
Inputs: endpoint.
remove_headerAIdempotent
Remove a custom HTTP header. Does not affect Authorization (use set_auth_token with empty string).
Inputs: key (required).
search_schemaARead-onlyIdempotent
Search the entire schema for types, fields, input fields, and enum values matching a substring (case-insensitive). Useful for finding things by partial name when the schema is large. Returns up to 100 hits by default.
Inputs: term (required), limit.
set_auth_tokenAIdempotent
Set a bearer token to send in the Authorization header on every request. Pass an empty string to clear. The token is held in process memory and never logged. For Basic auth or arbitrary headers, use set_basic_auth or set_headers / add_header instead.
Inputs: token (required).
set_basic_authAIdempotent
Configure HTTP Basic authentication. Replaces any bearer token. Pass empty username + password to clear.
Inputs: username (required), password (required).
set_headersAIdempotent
Replace the full set of custom HTTP headers. Use this for X-API-Key, X-Tenant, X-Trace-Id, etc. Authorization is handled separately by set_auth_token / set_basic_auth and will be re-applied on top of these headers. Pass an empty object to clear all custom headers.
Inputs: headers (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Every tool has a clearly distinct purpose: connection management, authentication, schema introspection, typed execution, and raw execution. There is no overlap or ambiguity between any pair of tools.
Tool names consistently follow a verb_noun pattern with underscores (e.g., connect_endpoint, list_queries, execute_typed_mutation). Minor variations like 'reload_schema' vs 'introspect_schema' are still consistent in style.
At 22 tools, the set is on the higher side of reasonable for a comprehensive GraphQL client server. While each tool serves a justifiable purpose, the count exceeds the typical well-scoped range of 3-15, making it slightly heavy but not excessive.
The tool surface covers the full lifecycle: connection setup, authentication (token, basic, custom headers), schema introspection, exploration (list, describe, search), query/mutation execution (raw and typed), and cache management. Subscriptions are omitted with a valid explanation. No obvious gaps.
Maintenance
Related MCP Connectors
Connect your AI agent to 300+ methods and 100+ live tools
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Discover, inspect and run 63,000+ agent tools from one balance. Pay per call, no subscriptions.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with Hasura GraphQL endpoints to discover schema structures and execute queries or mutations. It provides specialized tools for table introspection, data previewing, and performing data aggregations through natural language.-
- AlicenseBqualityDmaintenanceEnables AI assistants to execute GraphQL queries and retrieve schema information from any GraphQL endpoint.28MIT
- AlicenseAqualityDmaintenanceProvides comprehensive GraphQL introspection, filtering, and query/mutation execution with safety controls. Enables AI agents to explore and interact with GraphQL APIs through natural language.712 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to interact with any GraphQL API by introspecting the schema and exposing queries and mutations as MCP tools, with built-in pagination, semantic search, and framework adapters.29 npmMIT