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.

Use cases

Use cases for mcp-graphql-forge include creating custom API tools for client applications, integrating with third-party GraphQL services, and building a secure API layer for microservices.

How to use

To use mcp-graphql-forge, configure the server using environment variables and YAML files. Set the path to the configuration folder with the FORGE_CONFIG variable and enable debug logging with FORGE_DEBUG. Define the server attributes in the forge.yaml file, including the GraphQL endpoint and any necessary token commands.

Key features

Key features of mcp-graphql-forge include modular tool definitions through YAML configuration, secure API interactions, and the ability to extend functionality without altering application code.

Where to use

mcp-graphql-forge can be used in various fields such as web development, API integration, and microservices architecture where modular and secure API interactions are required.

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.

Configuration

The server is configured using environment variables and YAML files.

Environment Variables

• FORGE_CONFIG: Specifies the path to the folder containing the YAML configuration files (forge.yaml and tool definitions). Defaults to the current directory (.) if 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. Defaults to false.

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:

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

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

Run in SSE Mode

By default the server runs in stdio mode, but if you want to run in SSE mode, you can specify the --sse command line flag specifying the server name and port (ex: localhost:8080). This will run with the following endpoints that your MCP client can connect to:

• SSE Endpoint: /mcp/sse
• Message Endpoint: /mcp/message

Limitations

• Each instance of mcp-graphql-forge can only be used with a single GraphQL server at a single URL.
• All requests use the same Authorization header in the form of a Bearer token.
• The GraphQL queries are all exposed as Tools and not as Resources, even if they are not mutations. This is because not all MCP clients currently support Resources.