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. 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:
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.yamland tool definitions). If set, this takes precedence over theFORGE_CONFIGenvironment variable. If neither is set, the application will return an error and exit.--forgeDebug: If provided, enables detailed debug logging tostderr, including the obtained token and the full HTTP request/response for GraphQL calls. If set, this takes precedence over theFORGE_DEBUGenvironment variable.
Environment Variables
FORGE_CONFIG: Specifies the path to the folder containing the YAML configuration files (forge.yamland tool definitions). Used if--forgeConfigis not set.FORGE_DEBUG: If set totrue(case-insensitive), enables detailed debug logging tostderr, including the obtained token and the full HTTP request/response for GraphQL calls. Used if--forgeDebugis 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 serverurl: The URL of the GraphQL endpointtoken_command: The command to use to request the Bearer token for theAuthorizationheader (optional)env: A map of environment variables to pass to the token command (optional)env_passthrough: If set totrue, passes all environment variables used when invoking mcp-graphql-forge to the token command; if used in conjunction withenv, the variables fromenvwill take precedence (optional, defaults tofalse)
An example configuration would look like:
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 tooldescription: The description of the MCP toolquery: The GraphQL query to executeinputs: The list of inputs defined by the MCP tool and passed into the GraphQL query as variablesname: The name of the inputtype: The parameter type; can be 'string' or 'number'description: The description of the parameter for the MCP tool to userequired: 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 removedtoon: Converts JSON response to TOON format (Token-Oriented Object Notation) for efficient token usage with LLMs
An example configuration would look like:
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 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
./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-forgecan 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.
