mcp-graphql-forge is developed by UnitVectorY-Labs and is a lightweight, configuration-driven MCP server. Its core purpose is to convert any GraphQL endpoint into an MCP server and expose the GraphQL queries within it to AI agents in the form of "tools," thereby enabling intentional API interaction.
Main capabilities:
- Define MCP tools through YAML files, with each YAML file corresponding to one tool, specifying information such as the GraphQL query, parameters and their types, description, and whether they are required, allowing extension without modifying application code.
- Support adding MCP annotations to tools to indicate tool behavior, such as title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.
- Support configuring the GraphQL response output format: raw (passed through as-is, default), json (compact JSON with extra whitespace removed), toon (converted to TOON format, Token-Oriented Object Notation, used to optimize LLM token usage).
- Support obtaining a Bearer token via token_command for the Authorization header, and support configuring environment variables (env, env_passthrough).
- By default, it runs in stdio mode, and can also run in Streamable HTTP mode via the --http parameter, with an endpoint like http://localhost:8080/mcp。
Usage:
- Installation: Official versions are published on GitHub Releases, providing precompiled executables for macOS, Linux, and Windows; if Go is already installed, it can also be installed from source.
- Configuration: Configure through command-line parameters, environment variables, and YAML files. The command-line parameter --forgeConfig specifies the path to the folder containing forge.yaml and tool definition YAML files, and takes precedence over the environment variable FORGE_CONFIG; --forgeDebug enables detailed debug logging to stderr, and takes precedence over the environment variable FORGE_DEBUG.
- The general configuration file forge.yaml can specify: name (MCP server name), url (GraphQL endpoint URL), token_command (command to obtain the Bearer token, optional), env (environment variable mapping passed to the token command, optional), env_passthrough (whether to pass through all environment variables, optional, default false).
- The tool configuration YAML can specify: name, description, query, inputs (including name, type (string or number), description, required), annotations, output.
Applicable scenarios:
- Scenarios where an existing GraphQL API needs to be exposed to AI agents securely and with minimal scope.
- Scenarios where you want to manage the API tools available to agents through configuration rather than coding.
Limitations:
- Each mcp-graphql-forge instance can only be used for a single GraphQL server at a single URL.
- All GraphQL queries are exposed as Tools, not Resources, even if they are not mutations.
- If token_command is not configured, the Authorization header passed to the MCP server will be passed through to the backend GraphQL endpoint.
- More information regarding specific charges, pricing, platform support scope, effects, etc. is not yet provided.
