MCP GraphQL Forge

1[![GitHub release](https://img.shields.io/github/release/UnitVectorY-Labs/mcp-graphql-forge.svg)](https://github.com/UnitVectorY-Labs/mcp-graphql-forge/releases/latest) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Active](https://img.shields.io/badge/Status-Active-green)](https://guide.unitvectorylabs.com/bestpractices/status/#active) [![Go Report Card](https://goreportcard.com/badge/github.com/UnitVectorY-Labs/mcp-graphql-forge)](https://goreportcard.com/report/github.com/UnitVectorY-Labs/mcp-graphql-forge) [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/UnitVectorY-Labs/mcp-graphql-forge)](https://archestra.ai/mcp-catalog/unitvectory-labs__mcp-graphql-forge)
2 
3# mcp-graphql-forge
4 
5A lightweight, configuration-driven MCP server that exposes curated GraphQL queries as modular tools, enabling intentional API interactions from your agents.
6 
7## Purpose
8 
9`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.
10 
11## Releases
12 
13All 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.
14 
15Alternatively, if you have Go installed, you can install **mcp-graphql-forge** directly from source using the following command:
16 
17```bash
18go install github.com/UnitVectorY-Labs/mcp-graphql-forge@latest
19```
20 
21## Configuration
22 
23The server is configured using command line parameters, environment variables, and YAML files.
24 
25 
26### Command Line Parameters
27 
28- `--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.
29- `--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.
30 
31### Environment Variables
32 
33- `FORGE_CONFIG`: Specifies the path to the folder containing the YAML configuration files (`forge.yaml` and tool definitions). Used if `--forgeConfig` is not set.
34- `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.
35 
36### forge.yaml
37 
38The configuration folder uses a special configuration file `forge.yaml` that specifies the common configuration attributes.
39 
40The following attributes can be specified in the file:
41 
42- `name`: The name of the MCP server
43- `url`: The URL of the GraphQL endpoint
44- `token_command`: The command to use to request the Bearer token for the `Authorization` header (optional)
45- `env`: A map of environment variables to pass to the token command (optional)
46- `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`)
47 
48An example configuration would look like:
49 
50```yaml
51name: "ExampleServer"
52url: "https://api.github.com/graphql"
53token_command: "gh auth token"
54```
55 
56### Tool Configuration
57 
58All other YAML files located in the folder are treated as configuration files. Each YAML file defines a tool for the MCP server.
59 
60 
61The following attributes can be specified in the file:
62 
63- `name`: The name of the MCP tool
64- `description`: The description of the MCP tool
65- `query`: The GraphQL query to execute
66- `inputs`: The list of inputs defined by the MCP tool and passed into the GraphQL query as variables
67  - `name`: The name of the input
68  - `type`: The parameter type; can be 'string' or 'number'
69  - `description`: The description of the parameter for the MCP tool to use
70  - `required`: Boolean value specifying if the attribute is required
71- `annotations`: MCP annotations that provide hints about the tool's behavior (optional)
72  - `title`: A human-readable title for the tool, useful for UI display (optional)
73  - `readOnlyHint`: If true, indicates the tool does not modify its environment (optional, default: false)
74  - `destructiveHint`: If true, the tool may perform destructive updates (only meaningful when readOnlyHint is false) (optional, default: true)
75  - `idempotentHint`: If true, calling the tool repeatedly with the same arguments has no additional effect (only meaningful when readOnlyHint is false) (optional, default: false)
76  - `openWorldHint`: If true, the tool may interact with an "open world" of external entities (optional, default: true)
77- `output`: The output format for the GraphQL response (optional, defaults to "raw")
78  - `raw`: Passes through the server response as-is (default)
79  - `json`: Returns minimized JSON with unnecessary spacing removed
80  - `toon`: Converts JSON response to TOON format (Token-Oriented Object Notation) for efficient token usage with LLMs
81 
82An example configuration would look like:
83 
84```yaml
85name: "getUser"
86description: "Fetch basic information about a user by `login`, including their name, URL, and location."
87query: |
88  query ($login: String!) {
89    user(login: $login) {
90      id
91      name
92      url
93      location
94    }
95  }
96inputs:
97  - name: "login"
98    type: "string"
99    description: "The user `login` that uniquely identifies their account."
100    required: true
101annotations:
102  title: "Get User Information"
103  readOnlyHint: true
104  destructiveHint: false
105  idempotentHint: true
106  openWorldHint: true
107output: "toon"  # Optional: "raw" (default), "json", or "toon"
108```
109 
110### Output Formats
111 
112The `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.
113 
114#### Available Output Formats
115 
116**raw** (default)
117 
118- Passes through the GraphQL server response exactly as received
119- No transformation or modification is applied
120- Use when you need the original formatting from the server
121 
122**json**
123 
124- Returns minimized JSON with all unnecessary whitespace removed
125- Reduces token usage compared to formatted JSON
126- Ideal for reducing payload size while maintaining JSON compatibility
127- Automatically falls back to raw output if the response is not valid JSON
128 
129**toon**
130 
131- Converts the JSON response to TOON format (Token-Oriented Object Notation)
132- Can reduce token usage by 30-60% for uniform, tabular data
133- Optimized for LLM consumption with compact, human-readable output
134- Uses the [toon-format/toon-go](https://github.com/toon-format/toon-go) library
135- Automatically falls back to raw output if the response is not valid JSON or conversion fails
136 
137### Run in Streamable HTTP Mode
138 
139By 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:
140 
141`http://localhost:8080/mcp`
142 
143```bash
144./mcp-graphql-forge --http 8080
145```
146 
147If 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.
148 
149## Limitations
150 
151- Each instance of `mcp-graphql-forge` can only be used with a single GraphQL server at a single URL.
152- The GraphQL queries are all exposed as Tools and not as Resources, even if they are not mutations.
153