🚀 MCP GraphQL Forge

MCP GraphQL Forge is an MCP server that enables AI tools to access GraphQL APIs. It automatically generates MCP tools, validates parameters, and supports multiple transports, ensuring reliable AI interactions and consistent performance.

🚀 Quick Start

Installation

You can install MCP GraphQL Forge in the following ways:

Alternative Installation Methods

# Via Smithery (recommended)
npx @smithery/cli install @toolprint/mcp-graphql-forge --client claude

# Via npm
npm install -g @toolprint/mcp-graphql-forge

Getting Started Guide

⚠️ Important Note

Docker runtime support is currently a work in progress. For production deployments, we recommend using the TypeScript runtime on platforms like Smithery.

Quick Start with HTTP Mode (Recommended for Development)

1. Start the server:

   # Start serving it with the Streamable HTTP transport
   GRAPHQL_ENDPOINT="https://your-api.com/graphql" npx -y @toolprint/mcp-graphql-forge --transport http --port 3001
   

2. Connect with MCP Inspector:

   # In another terminal, launch the inspector
   npx @modelcontextprotocol/inspector
   

3. With authentication:

   # Using environment variables for configuration
   export GRAPHQL_ENDPOINT="https://api.github.com/graphql"
   export GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN"
   npx @toolprint/mcp-graphql-forge --transport http --port 3001
   
   # Or all in one line
   GRAPHQL_ENDPOINT="https://api.github.com/graphql" GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN" npx @toolprint/mcp-graphql-forge --transport http --port 3001
   

Direct AI Integration (Claude/Cursor)

Create an mcp.json in your project root. This will run it in stdio mode.

{
    "mcpServers": {
        "mcp-graphql-forge": {
            "command": "npx",
            "args": [
              "-y",
              "@toolprint/mcp-graphql-forge"
            ],
            "env": {
                "GRAPHQL_ENDPOINT": "https://your-api.com/graphql",
                "GRAPHQL_AUTH_HEADER": "Bearer YOUR_TOKEN"
            }
        }
    }
}

Schema Management

1. Pre-generate schema:

   # Generate schema without starting server
   GRAPHQL_ENDPOINT="https://your-api.com/graphql" mcp-graphql-forge introspect
   
   # Start server using pre-generated schema
   mcp-graphql-forge --no-introspection --transport http --port 3001
   

2. Custom schema location:

   # Generate schema in custom location
   SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge introspect
   
   # Use custom schema location
   SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge --no-introspection --transport http --port 3001
   

3. Force schema regeneration:

   # Force regenerate schema even if it exists
   mcp-graphql-forge introspect --force
   
   # Regenerate and start server
   mcp-graphql-forge --force-introspection --transport http --port 3001
   

Advanced Configuration

# Multiple custom headers
export GRAPHQL_HEADER_X_API_KEY="your-api-key"
export GRAPHQL_HEADER_X_CLIENT_ID="your-client-id"
mcp-graphql-forge --transport http --port 3001

# Development mode with auto-reload on schema changes
mcp-graphql-forge --transport http --port 3001 --watch

✨ Features

• Tool Generation: Creates MCP tools from GraphQL schema introspection.
• Parameter Validation: Multi-layer validation prevents GraphQL errors.
• Dual Transport: Supports stdio (AI tools) and HTTP (development/testing).
• Schema Management: Optional pre-introspection and caching.
• Authentication: Flexible header configuration for authenticated endpoints [Experimental].

🛠️ How It Works

1. Schema Introspection

🗂️  Building field selection cache for all types...
📊 Generated field selections for 44 types  
💾 Field selection cache contains 44 full selections and 5 minimal selections
Generated 63 tools from GraphQL schema:
  - 30 query tools
  - 33 mutation tools

2. Intelligent Tool Generation

For a GraphQL schema like:

type Query {
  user(id: ID!): User
  articles(filters: ArticleFiltersInput, pagination: PaginationArg): [Article]
}

type Mutation {
  createUser(input: CreateUserInput!): User
}

Fast MCP GraphQL automatically generates:

• ✅ query_user - with required id parameter validation
• ✅ query_articles - with optional filtering and pagination
• ✅ mutation_createUser - with input validation and complete field selections

3. Smart Field Selection

Instead of manual GraphQL query construction:

# ❌ Error-prone manual approach
query {
  articles {
    # Missing required field selections!
    author {
      # Circular reference issues!
    }
  }
}

Fast MCP GraphQL generates optimal queries automatically:

# ✅ Auto-generated with full field selections
query articlesOperation($filters: ArticleFiltersInput, $pagination: PaginationArg) {
  articles(filters: $filters, pagination: $pagination) {
    documentId
    title
    description
    author {
      documentId
      name
      email
      articles_connection {
        nodes { documentId }  # Circular reference handled!
      }
    }
    category {
      documentId
      name
      articles { documentId }  # Cached selection reused!
    }
  }
}

🏗️ Architecture

Caching System

• Type-Level Caching: Each GraphQL type's field selection is computed once and reused.
• Circular Reference Resolution: Intelligent detection with minimal field fallbacks.
• Consistent Output: Same type always generates identical field selections.

Validation Pipeline

1. JSON Schema Validation: MCP clients validate parameters before execution.
2. Server-Side Validation: Prevents execution with missing required parameters.
3. GraphQL Validation: Final validation at the GraphQL layer.

Transport Support

• Stdio Transport: For MCP client integration (default).
• HTTP Transport: RESTful interface with MCP 2025 Streamable HTTP specification.
• Session Management: Automatic session handling for HTTP transport.

📚 API Reference

CLI Options

mcp-graphql-forge [options]

Options:
  --transport <type>     Transport type: stdio or http (default: stdio)
  --port <number>        Port for HTTP transport (default: 3000)
  --no-introspection     Skip schema introspection (use cached schema)
  --version              Show version number
  --help                 Show help

Environment Variables

Generated Tool Schema

Each generated tool follows this pattern:

{
  name: "query_user",
  description: "Execute GraphQL query: user",
  inputSchema: {
    type: "object",
    properties: {
      id: { type: "string" }
    },
    required: ["id"]  // Only truly required parameters
  }
}

🧪 Testing

Comprehensive Test Suite

• 40+ Test Cases: Covering all functionality and edge cases.
• Real-World Scenarios: Tests against actual GraphQL schemas (Strapi, GitHub, etc.).
• Security Testing: Prototype pollution protection and input validation.
• Performance Testing: Cache efficiency and field selection optimization.

# Run all tests
npm test

# Run specific test suites
npm test -- src/__tests__/field-selection-cache.test.ts
npm test -- src/__tests__/server-validation.test.ts
npm test -- src/__tests__/graphql-execution.test.ts

# Coverage report
npm run test:coverage

Integration Testing

# Test with real GraphQL endpoints
GRAPHQL_ENDPOINT="https://countries.trevorblades.com/" npm test

# Test caching performance
npm run test:performance

🛡️ Security

Parameter Validation

• Required Parameter Enforcement: Prevents GraphQL variable errors.
• Null/Undefined Checking: Validates parameter presence and values.
• Prototype Pollution Protection: Uses secure property checking methods.

Schema Security

• Input Sanitization: All GraphQL inputs are properly typed and validated.
• Circular Reference Protection: Prevents infinite recursion in field selections.
• Header Validation: Secure header handling for authentication.

🚀 Performance

Benchmarks

• Schema Introspection: ~10ms for typical schemas.
• Tool Generation: ~5ms with caching enabled.
• Field Selection: Pre-computed and cached for instant access.
• Memory Usage: Efficient caching with minimal memory footprint.

Optimization Features

• Field Selection Caching: Eliminates redundant field selection computation.
• Schema Caching: Optional schema persistence for faster restarts.
• Minimal GraphQL Queries: Only requests necessary fields.
• Connection Pooling: Efficient HTTP client management.

📖 Examples

Real-World Usage

</details>

<details>
<summary>🔸 <strong>GitHub API Integration</strong></summary>
```bash
# Connect to GitHub GraphQL API
export GRAPHQL_ENDPOINT="https://api.github.com/graphql"
export GRAPHQL_AUTH_HEADER="Bearer YOUR_GITHUB_TOKEN"
mcp-graphql-forge

# Generates tools like:
# - query_repository, query_user, query_organization
# - query_search (with intelligent result type handling)
# - mutation_createIssue, mutation_addComment

</details>

### Custom Schema Example
```typescript
// Example: Blog Platform Schema
type Query {
  posts(published: Boolean, authorId: ID): [Post]
  post(slug: String!): Post
  authors: [Author]
}

type Mutation {
  createPost(input: CreatePostInput!): Post
  publishPost(id: ID!): Post
}

// Generated Tools:
// ✅ query_posts (published?: boolean, authorId?: string)
// ✅ query_post (slug: string) ← Required parameter enforced
// ✅ query_authors () ← No parameters
// ✅ mutation_createPost (input: CreatePostInput) ← Validated input
// ✅ mutation_publishPost (id: string) ← Required parameter enforced