MCP GraphQL Forge

Configuration

The server is configured using command line parameters, 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). 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.

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:

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"