mcp-graphql-forge

[](https://github.com/UnitVectorY-Labs/mcp-graphql-forge/releases/latest) [](https://opensource.org/licenses/MIT) [](https://guide.unitvectorylabs.com/bestpractices/status/#active) [](https://goreportcard.com/report/github.com/UnitVectorY-Labs/mcp-graphql-forge) # mcp-graphql-forge A lightweight, configuration-driven MCP server that exposes curated GraphQL queries as modular tools, enabling intentional API interactions from your agents. ## Purpose `mcp-graphql-forge` lets you turn any GraphQL endpoint into an MCP server whose tools are defined in YAML files that specify the GraphQL queries and their parameters. This allows you to create a modular, secure, and minimal server that can be easily extended without modifying the application code. ## Releases All official versions of **mcp-graphql-forge** are published on [GitHub Releases](https://github.com/UnitVectorY-Labs/mcp-graphql-forge/releases). Since this MCP server is written in Go, each release provides pre-compiled executables for macOS, Linux, and Windows—ready to download and run. Alternatively, if you have Go installed, you can install **mcp-graphql-forge** directly from source using the following command: ```bash go install github.com/UnitVectorY-Labs/mcp-graphql-forge@latest ``` ## Configuration The server is configured using command line parameters, environment variables, and YAML files. ### Command Line Parameters - `--forgeConfig`: Specifies the path to the folder containing the YAML configuration files (`forge.yaml` and tool definitions). If set, this takes precedence over the `FORGE_CONFIG` environment variable. If neither is set, the application will return an error and exit. - `--forgeDebug`: If provided, enables detailed debug logging to `stderr`, including the obtained token and the full HTTP request/response for GraphQL calls. If set, this takes precedence over the `FORGE_DEBUG` environment variable. ### Environment Variables - `FORGE_CONFIG`: Specifies the path to the folder containing the YAML configuration files (`forge.yaml` and tool definitions). Used if `--forgeConfig` is not set. - `FORGE_DEBUG`: If set to `true` (case-insensitive), enables detailed debug logging to `stderr`, including the obtained token and the full HTTP request/response for GraphQL calls. Used if `--forgeDebug` is not set. ### forge.yaml The configuration folder uses a special configuration file `forge.yaml` that specifies the common configuration attributes. The following attributes can be specified in the file: - `name`: The name of the MCP server - `url`: The URL of the GraphQL endpoint - `token_command`: The command to use to request the Bearer token for the `Authorization` header (optional) - `env`: A map of environment variables to pass to the token command (optional) - `env_passthrough`: If set to `true`, passes all environment variables used when invoking mcp-graphql-forge to the token command; if used in conjunction with `env`, the variables from `env` will take precedence (optional, defaults to `false`) An example configuration would look like: ```yaml name: "ExampleServer" url: "https://api.github.com/graphql" token_command: "gh auth token" ``` ### Tool Configuration All other YAML files located in the folder are treated as configuration files. Each YAML file defines a tool for the MCP server. The following attributes can be specified in the file: - `name`: The name of the MCP tool - `description`: The description of the MCP tool - `query`: The GraphQL query to execute - `inputs`: The list of inputs defined by the MCP tool and passed into the GraphQL query as variables - `name`: The name of the input - `type`: The parameter type; can be 'string' or 'number' - `description`: The description of the parameter for the MCP tool to use - `required`: Boolean value specifying if the attribute is required - `annotations`: MCP annotations that provide hints about the tool's behavior (optional) - `title`: A human-readable title for the tool, useful for UI display (optional) - `readOnlyHint`: If true, indicates the tool does not modify its environment (optional, default: false) - `destructiveHint`: If true, the tool may perform destructive updates (only meaningful when readOnlyHint is false) (optional, default: true) - `idempotentHint`: If true, calling the tool repeatedly with the same arguments has no additional effect (only meaningful when readOnlyHint is false) (optional, default: false) - `openWorldHint`: If true, the tool may interact with an "open world" of external entities (optional, default: true) - `output`: The output format for the GraphQL response (optional, defaults to "raw") - `raw`: Passes through the server response as-is (default) - `json`: Returns minimized JSON with unnecessary spacing removed - `toon`: Converts JSON response to TOON format (Token-Oriented Object Notation) for efficient token usage with LLMs An example configuration would look like: ```yaml name: "getUser" description: "Fetch basic information about a user by `login`, including their name, URL, and location." query: | query ($login: String!) { user(login: $login) { id name url location } } inputs: - name: "login" type: "string" description: "The user `login` that uniquely identifies their account." required: true annotations: title: "Get User Information" readOnlyHint: true destructiveHint: false idempotentHint: true openWorldHint: true output: "toon" # Optional: "raw" (default), "json", or "toon" ``` ### Output Formats The `output` configuration parameter allows you to specify how the GraphQL response should be formatted. This is particularly useful when working with LLMs, as different formats can optimize for token efficiency. #### Available Output Formats **raw** (default) - Passes through the GraphQL server response exactly as received - No transformation or modification is applied - Use when you need the original formatting from the server **json** - Returns minimized JSON with all unnecessary whitespace removed - Reduces token usage compared to formatted JSON - Ideal for reducing payload size while maintaining JSON compatibility - Automatically falls back to raw output if the response is not valid JSON **toon** - Converts the JSON response to TOON format (Token-Oriented Object Notation) - Can reduce token usage by 30-60% for uniform, tabular data - Optimized for LLM consumption with compact, human-readable output - Uses the [toon-format/toon-go](https://github.com/toon-format/toon-go) library - Automatically falls back to raw output if the response is not valid JSON or conversion fails ### Run in Streamable HTTP Mode By default the server runs in stdio mode, but if you want to run in streamable HTTP mode, you can specify the `--http` command line flag with the server address and port (ex: `--http 8080`). This will run the server with the following endpoint that your MCP client can connect to: `http://localhost:8080/mcp` ```bash ./mcp-graphql-forge --http 8080 ``` If you do not specify `token_command` in the configuration, the "Authorization" header, if passed to the MCP server, will be passed through from the incoming MCP request to the backend GraphQL endpoint. ## Limitations - Each instance of `mcp-graphql-forge` can only be used with a single GraphQL server at a single URL. - The GraphQL queries are all exposed as Tools and not as Resources, even if they are not mutations.