mcp-graphql-forge

MCP GraphQL Forge is a server that automatically generates MCP tools from a GraphQL schema. By introspecting a GraphQL endpoint, it creates a suite of MCP tools that allow AI agents to query and mutate data through GraphQL with validated inputs and structured field selections. The server supports both stdio and HTTP transports, enabling seamless development (stdio) and production-like testing (HTTP). It also caches schema and field selections to ensure consistent tool behavior across runs and reduces repeated introspection overhead. This makes it easier to integrate GraphQL-backed APIs into AI workflows without writing individual tools manually.

Prerequisites:

• Node.js 16+ and npm (or yarn)
• Basic familiarity with npm/npx and environment variables

Installation and setup:

# Quick install and run in HTTP mode (recommended for development)
GRAPHQL_ENDPOINT="https://your-graphql-endpoint.example.com/graphql" GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN" npx -y @toolprint/mcp-graphql-forge --transport http --port 3001

Option 1: Run directly with npx (no global install required)

GRAPHQL_ENDPOINT="https://your-graphql-endpoint.example.com/graphql" GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN" npx -y @toolprint/mcp-graphql-forge --transport http --port 3001

Option 2: Install globally (optional for repeated use)

npm install -g @toolprint/mcp-graphql-forge
GRAPHQL_ENDPOINT="https://your-graphql-endpoint.example.com/graphql" GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN" mcp-graphql-forge --transport http --port 3001

Option 3: Use the MCP config format (recommended for multi-server setups)

# Output example shows how to configure the server in mcp.json (or similar)
# See the repository for schema and introspection options

Environment variable tips:

• GRAPHQL_ENDPOINT: Set the GraphQL API endpoint to introspect.
• GRAPHQL_AUTH_HEADER: Provide a token or credentials header if your GraphQL API requires authentication.
• GRAPHQL_HEADER_*: You can add additional custom headers (e.g., GRAPHQL_HEADER_X_API_KEY) as needed.
• SCHEMA_PATH: If you pre-generate a schema, point the tool to the cached schema file.
• PORT: If using HTTP transport, choose the port (default is 3001).

Common issues:

• If you see authentication errors, verify that GRAPHQL_AUTH_HEADER is correctly formatted (e.g., Bearer TOKEN).
• When using introspection, ensure the endpoint is reachable from the host running the MCP server.
• If the server cannot start due to port in use, choose a different port via --port.

Performance tip:

• Enable schema caching to avoid repeated introspection in development. Use --no-introspection when you have a cached schema.