mcp‑graphql‑forge

mcp‑graphql‑forge is a lightweight, configuration‑driven MCP server that turns any GraphQL endpoint into a set of fine‑grained, secure tools. By defining queries in YAML files rather than code, it lets developers expose only the operations that agents are allowed to call, eliminating accidental data leaks and simplifying maintenance. The server runs as a minimal Go binary that reads a single configuration folder, validates the GraphQL schema against each query, and registers every tool with the MCP protocol.

Problem Solved

When building AI assistants that need to pull data from third‑party APIs, developers often end up writing custom wrappers or exposing the entire GraphQL surface. This can lead to over‑exposure of sensitive fields, brittle code that must be updated for every schema change, and a hard‑to‑audit permission model. mcp‑graphql‑forge addresses these pain points by providing a declarative, file‑based approach: only the queries listed in YAML files become available as tools. Each tool can specify its own parameters, documentation, and optional authentication logic, ensuring that agents interact with APIs in a controlled, auditable manner.

Core Functionality

• YAML‑driven tool definition – Every YAML file in the configuration folder becomes an MCP tool. The file declares a friendly name, a human‑readable description, the exact GraphQL query, and any required variables.
• Secure token handling – The server can invoke an external command to fetch a bearer token, optionally passing environment variables. This supports OAuth flows or other custom authentication mechanisms without hard‑coding secrets.
• Command‑line & environment configuration – The path to the config folder, debug mode, and other runtime options can be supplied via flags or environment variables, giving developers flexibility in CI/CD pipelines or local development.
• Runtime validation – Before registering a tool, the server checks that the query is syntactically valid against the target GraphQL endpoint, preventing runtime failures when an agent calls a malformed query.

Use Cases

• Data‑centric assistants – A customer support bot that pulls ticket details from a GraphQL API can expose only the query, keeping all other data hidden.
• CI/CD automation – DevOps tools can use mcp‑graphql‑forge to expose GraphQL queries for deployment status, pipeline logs, or resource metrics in a single, versioned configuration folder.
• Internal knowledge bases – Teams can expose curated queries against a corporate GraphQL service, allowing agents to retrieve policy documents or inventory data without granting full API access.

Integration with AI Workflows

Once running, the server advertises its tools via the MCP protocol. An agent can request a tool by name, supply the required variables, and receive the GraphQL response in JSON. Because each tool is a first‑class MCP resource, it can be combined with other tools, prompts, or sampling strategies in a single prompt chain. Developers can version the YAML files alongside their codebase, ensuring that any changes to available queries are tracked and auditable.

Unique Advantages

• Zero‑code deployment – No Go code changes are needed to add or remove tools; simply drop a new YAML file into the config folder.
• Fine‑grained security – Only explicitly defined queries are exposed, reducing attack surface.
• Built‑in authentication plumbing – Supports dynamic token retrieval without storing secrets in the server.
• Cross‑platform binaries – Precompiled executables for macOS, Linux, and Windows make it easy to ship the server in any environment.

mcp‑graphql‑forge offers a clean, declarative way to expose GraphQL APIs as MCP tools, empowering developers to build secure, maintainable AI assistants that can query external data sources with confidence.