mcp-graphql-forge

What is mcp-graphql-forge?

mcp-graphql-forge is a lightweight, configuration-driven MCP server that exposes curated GraphQL queries as modular tools, enabling intentional API interactions from your agents. It 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.

How to use mcp-graphql-forge?

Install by downloading a pre-compiled executable from GitHub Releases for macOS, Linux, or Windows, or via go install github.com/UnitVectorY-Labs/mcp-graphql-forge@latest. Configure with the --forgeConfig command line parameter (or FORGE_CONFIG environment variable) pointing to a folder containing forge.yaml (server URL, optional token command) and tool definition YAML files. Run in stdio mode by default; add --http 8080 for streamable HTTP mode.

Key features of mcp-graphql-forge

• Configuration-driven YAML tool definitions for modularity.
• Supports multiple output formats: raw, json, and TOON.
• Optional bearer token fetching via command.
• Annotations for tool metadata (read-only, idempotent, etc.).
• Streamable HTTP mode with --http flag.
• Pre-compiled binaries for all major platforms.

Use cases of mcp-graphql-forge

• Expose specific GraphQL queries as safe, intentional MCP tools.
• Create a minimal, secure MCP server for a single GraphQL endpoint.
• Optimize LLM token usage by converting GraphQL responses to TOON format.
• Enable agents to fetch curated data from any GraphQL API.

FAQ from mcp-graphql-forge

What is mcp-graphql-forge?

It is a lightweight MCP server that transforms a GraphQL endpoint into a set of MCP tools, where each tool is defined in a YAML file specifying the query and its parameters.

What authentication methods are supported?

Authentication is handled via an optional token_command in forge.yaml that fetches a Bearer token. If no token command is provided, the Authorization header from the incoming MCP request is passed through to the GraphQL endpoint.

What output formats are available?

The server supports three output formats: raw (pass-through), json (minimized), and toon (Token-Oriented Object Notation, which can reduce token usage by 30-60% for tabular data).

How does mcp-graphql-forge run?

By default it runs in stdio mode. It can also run in streamable HTTP mode by specifying --http <port>, which exposes an endpoint at http://localhost:<port>/mcp.

What are the limitations of mcp-graphql-forge?

Each instance can only connect to a single GraphQL server at a single URL. All GraphQL queries are exposed as tools, not as resources.