graphql -bridge

The GraphQL MCP Bridge turns a GraphQL schema into a set of MCP tools that are validated and type-safe at runtime. It preserves GraphQL field descriptions as tool descriptions and supports flexible configuration to control which operations are generated and how they’re named. You can feed a GraphQL schema into the bridge, obtain MCP-compatible tool definitions, and execute those tools with automatic input and output validation powered by Zod. This enables AI systems to interact with GraphQL services through the MCP protocol with strong guarantees about inputs, outputs, and field selections.

To use the bridge in practice, install the MCP server, start it, and point your MCP consumer at the server. The generated tools expose GraphQL query-like operations that accept strongly typed inputs and allow you to specify a safe subset of fields to fetch. The runtime validation ensures invalid field selections or mismatched inputs fail fast, making integration robust for production use.

Prerequisites:

• Node.js v24 or newer installed on your system
• npm, pnpm, or yarn for package management
• Git to clone the repository (optional if using npm install)

Install from npm:

1. npm install -g graphql-mcp-bridge (or add to your project: npm install graphql-mcp-bridge)
2. Ensure you have a GraphQL schema ready to convert into MCP tools, or reference the schema in your project

Configuration and running:

1. Create a minimal server entry point (server.js) that initializes and exposes the MCP bridge using the library. Example contents would import the bridge, configure the GraphQL schema, and start listening on a port.
2. Start the server: node path/to/server.js
3. Verify the server is running by curling the MCP endpoint or using your MCP client to enumerate tools.

Optional:

• If you prefer a containerized approach, you can build a Docker image that runs node path/to/server.js and publishes the MCP port.
• Use environment variables to configure host, port, and any authentication if you add it to your server.

Notes:

• Ensure your GraphQL schema covers the necessary types and relationships for your MCP tools.
• Keep dependencies up to date to benefit from validation improvements and runtime safety.

Environment variables you may want to consider:

• PORT: Port to run the MCP server on (default 3000)
• HOST: Bind address (default 0.0.0.0)
• GRAPHQL_SCHEMA_PATH: Optional path to a local GraphQL schema file to be loaded at startup Common issues:
• If the server fails to start, check Node.js version compatibility and ensure the entry file path is correct
• Validate that your schema contains the necessary Query types for tool generation; very large schemas may benefit from incremental loading
• When integrating with MCP clients, ensure the client points to the correct host/port and handles validation errors gracefully