mcp-graphql-enhanced

You are using an enhanced MCP server for GraphQL that acts as a bridge between large language models and GraphQL APIs. It provides a drop-in replacement with dynamic headers, robust variable parsing, a built-in GraphiQL IDE, dual transport modes, and deep observability to help you test and evolve your GraphQL integration with models.

How to use

This MCP server lets you connect an LLM or agent to your GraphQL API through two transport methods: a local standard input/output flow and a live HTTP/JSON-RPC interface. Start the server with environment variables to configure the endpoint, headers, and behavior. Use the HTTP interface for web or external clients, and keep the STDIO flow for CLI-based tooling and rapid testing. You can test queries and mutations (mutations disabled by default) and inspect introspection results to keep prompts focused and efficient.

For practical usage, set the endpoint and headers you need, choose whether to enable mutations, and decide if you want the HTTP interface available. Then, use the built-in GraphiQL IDE to compose and test queries in a visual environment, or call the tool via the JSON-RPC endpoint to run queries from automation. Use the introspection and query tools to explore your schema, and rely on the observability features to understand how the LLM interacts with your graph data.

How to install

Prerequisites: ensure you have a modern runtime environment such as Node.js installed on your machine, along with a compatible package manager (npm or npx). You may also want Docker if you prefer containerized runs.

Step 1: Install dependencies and prepare the environment. If you are starting from source, install dependencies and build if required.

Step 2: Run the server using one of the provided configuration options shown in the examples. You can run via npx for quick usage, via Docker for isolation, or build locally and run with Node.

Step 3: Verify the server starts and note the port. The server defaults to port 6274 and will automatically adjust if that port is busy. Check the final bound port in the logs.

Additional sections

Environment variables you can set to customize the server behavior are listed here. Use them to point to your GraphQL endpoint, provide authentication headers, toggle mutations, name your server, and control debugging.

Environment variable notes: ENDPOINT defines the GraphQL API URL, HEADERS contains a JSON string of request headers, ALLOW_MUTATIONS toggles mutation support, NAME sets the MCP server name, SCHEMA points to a local GraphQL schema file or URL, MCP_PORT chooses the HTTP/JSON-RPC port, ENABLE_HTTP toggles the HTTP transport, and DEBUG enables detailed logs.

Tips for testing: use curl to exercise the HTTP endpoint when enabled, and verify the health endpoint to confirm the server is running. Filter introspection to avoid large schema dumps, and use the inspector tool to validate the setup end-to-end.

Security: mutations are disabled by default to prevent unintended data changes. Always validate headers and schema inputs in production, use HTTPS endpoints, and prefer short-lived tokens.

Notes on usage patterns and features

Built-in GraphiQL IDE provides a visual playground at the root endpoint and can be accessed when HTTP is enabled. Headers configured via environment variables automatically flow into the GraphiQL Headers tab for testing convenience.

Advanced observability includes automated Cypher extraction and cleaning from GraphQL extensions to help you understand how your queries map to database operations.

The server supports both local and remote workflow options. If you work with a server that regenerates GraphQL types on the fly, you’ll get proactive diagnostics and gap analysis to keep schemas aligned with application needs.

Available tools

introspect-schema

Retrieves the GraphQL schema or a filtered subset of it, using a local file, URL, or live introspection.

query-graphql

Executes GraphQL queries against the configured endpoint, with optional mutation support based on configuration.