# Mcp Graphql Forge

> A lightweight, configuration-driven MCP server that exposes curated GraphQL queries as modular tools, enabling intentional API interactions from your agents.

- **Type:** MCP server
- **Install:** `agentstack add mcp-unitvectory-labs-mcp-graphql-forge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [UnitVectorY-Labs](https://agentstack.voostack.com/s/unitvectory-labs)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [UnitVectorY-Labs](https://github.com/UnitVectorY-Labs)
- **Source:** https://github.com/UnitVectorY-Labs/mcp-graphql-forge

## Install

```sh
agentstack add mcp-unitvectory-labs-mcp-graphql-forge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [UnitVectorY-Labs](https://github.com/UnitVectorY-Labs)
- **Source:** [UnitVectorY-Labs/mcp-graphql-forge](https://github.com/UnitVectorY-Labs/mcp-graphql-forge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-unitvectory-labs-mcp-graphql-forge
- Seller: https://agentstack.voostack.com/s/unitvectory-labs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.