graphql-inspector-mcp

GraphQL Introspection MCP Server

A Model Context Protocol (MCP) server that provides comprehensive GraphQL introspection capabilities with filtering and detailed analysis features.

Features

• Complete Schema Introspection: Get full GraphQL schema with SDL and structured data
• Smart Filtering: Filter queries, mutations, and types with search patterns
• Detailed Analysis: Get comprehensive information about specific types and fields
• Query Execution: Execute read-only GraphQL queries against any endpoint
• Mutation Support: Execute GraphQL mutations with explicit opt-in via ALLOW_MUTATIONS flag
• Safety Controls: 3-layer protection with tool listing, execution guards, and GraphQL AST validation

Safety & Permissions

Default Mode (Read-Only)

By default, only read-only operations are available:

• All 6 introspection tools (schema, queries, mutations, types, type details, field details)
• execute_query — executes GraphQL queries only

Dangerous Mode (Mutations Enabled)

To enable mutation execution, set the ALLOW_MUTATIONS environment variable:

ALLOW_MUTATIONS=true npx graphql-inspector-mcp

Or in your MCP config:

{
  "mcpServers": {
    "graphql-introspection": {
      "command": "npx",
      "args": ["-y", "graphql-inspector-mcp"],
      "env": {
        "ALLOW_MUTATIONS": "true"
      }
    }
  }
}

When enabled, the execute_mutation tool becomes available.

Safety Architecture

Three layers of protection prevent unauthorized mutations:

• Tool Listing: execute_mutation is hidden from tool discovery when ALLOW_MUTATIONS is not set
• Execution Guard: Even if called directly, execute_mutation rejects when not in dangerous mode
• AST Validation: GraphQL documents are parsed and validated — operation type is verified at the AST level, not string matching

• MCP Annotations: All tools annotated with readOnlyHint for MCP-aware clients
• Authentication Support: Basic Auth and Bearer token authentication
• Caching: In-memory caching with 5-minute expiration for better performance
• AI-Friendly Output: Structured JSON responses optimized for AI agents

Installation

npm install
npm run build

Usage

Using npx

You can run the tool directly via npx:

npx graphql-inspector-mcp

This will start the MCP server and expose GraphQL introspection tools.

CLI Arguments

The following arguments can be provided via JSON config, environment variables, or MCP tool requests. They are not traditional CLI flags, but are passed as options to the server or tools.

Argument	Type	Description	Example Value
endpoint	string	GraphQL endpoint URL (default: http://localhost:5555/graphql)	http://localhost:5555/graphql
username	string	Username for basic authentication (optional)	admin
password	string	Password for basic authentication (optional)	secret
bearer_token	string	Bearer token for authentication (optional)	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
search	string	Search pattern to filter queries, mutations, or types (case-insensitive)	user
detailed	boolean	Return detailed information (default: false)	true
kind	string	Filter by type kind (OBJECT, SCALAR, ENUM, INTERFACE, UNION, INPUT_OBJECT)	OBJECT
type_name	string	Name of the type to get details for	User
field_name	string	Name of the field to get details for	getUser
operation_type	string	Type of operation (query or mutation)	query
query	string	GraphQL query or mutation string	query { users { id name } }
variables	object	Variables for the GraphQL operation (optional)	{"userId": "123"}
operation_name	string	Name of the operation to execute (optional, for multi-operation documents)	GetUserById

Usage Example

npx graphql-inspector-mcp

With config file (mcp.config.json):

{
  "mcpServers": {
    "graphql-introspection": {
      "command": "npx",
      "args": [
        "-y",
        "kokorolx/graphql-inspector-mcp"
      ],
      "options": {
        "endpoint": "http://localhost:5555/graphql"
      }
    }
  }
}

Or via environment variables:

export GRAPHQL_DEFAULT_ENDPOINT="http://localhost:4000/graphql"
export CACHE_DURATION_MS="600000"

Or via MCP tool request JSON:

{
  "endpoint": "http://localhost:5555/graphql",
  "search": "user",
  "detailed": true
}

MCP Config File

The MCP config file allows you to customize server settings and tool behavior. By default, the config file should be named mcp.config.json and placed in your project root.

Example mcp.config.json:

{
  "mcpServers": {
    "graphql-introspection": {
      "command": "npx",
      "args": [
        "-y",
        "kokorolx/graphql-inspector-mcp"
      ],
      "options": {
        "endpoint": "http://localhost:5550/graphql"
      }
    }
  }
}

• Location: Project root (e.g., ./mcp.config.json)
• Format: Standard JSON
• Usage: The MCP client will automatically detect and use this configuration when starting the server.

Available Tools

1. get_graphql_schema

Get complete GraphQL schema introspection with SDL and structured data.

{
  "endpoint": "http://localhost:5555/graphql",
  "username": "optional_username",
  "password": "optional_password",
  "bearer_token": "optional_bearer_token"
}

2. filter_queries

Filter and list available GraphQL queries with optional search.

{
  "endpoint": "http://localhost:5555/graphql",
  "search": "user",
  "detailed": true
}

3. filter_mutations

Filter and list available GraphQL mutations with optional search.

{
  "endpoint": "http://localhost:5555/graphql",
  "search": "create",
  "detailed": false
}

4. filter_types

Filter and list available GraphQL types by kind and search pattern.

{
  "endpoint": "http://localhost:5555/graphql",
  "search": "User",
  "kind": "OBJECT",
  "detailed": true
}

Supported type kinds:

• OBJECT - Object types
• SCALAR - Scalar types
• ENUM - Enumeration types
• INTERFACE - Interface types
• UNION - Union types
• INPUT_OBJECT - Input object types

5. get_type_details

Get comprehensive information about a specific GraphQL type.

{
  "type_name": "User",
  "endpoint": "http://localhost:5555/graphql"
}

6. get_field_details

Get detailed information about a specific query or mutation field.

{
  "field_name": "getUser",
  "operation_type": "query",
  "endpoint": "http://localhost:5555/graphql"
}

7. execute_query

Execute a read-only GraphQL query against the endpoint.

{
  "query": "query { users { id name email } }",
  "variables": {},
  "endpoint": "http://localhost:5555/graphql"
}

8. execute_mutation

Execute a GraphQL mutation (requires ALLOW_MUTATIONS=true).

{
  "query": "mutation { createUser(name: \"John\") { id name } }",
  "variables": {},
  "endpoint": "http://localhost:5555/graphql"
}

Authentication

The server supports multiple authentication methods:

Basic Authentication

{
  "endpoint": "https://api.example.com/graphql",
  "username": "your_username",
  "password": "your_password"
}

Bearer Token

{
  "endpoint": "https://api.example.com/graphql",
  "bearer_token": "your_jwt_token"
}

Response Format

All responses are structured JSON optimized for AI processing:

Success Response

{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "data": {
    // ... relevant data
  }
}

Error Response

{
  "success": false,
  "error": "Error description",
  "endpoint": "http://localhost:5555/graphql"
}

Example Responses

Filter Queries (Summary)

{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "search_term": "user",
  "queries": [
    {
      "name": "getUser",
      "description": "Fetch a user by ID",
      "deprecated": false,
      "deprecation_reason": null
    },
    {
      "name": "searchUsers",
      "description": "Search users by criteria",
      "deprecated": false,
      "deprecation_reason": null
    }
  ],
  "total": 2
}

Filter Queries (Detailed)

{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "queries": [
    {
      "name": "getUser",
      "description": "Fetch a user by ID",
      "deprecated": false,
      "deprecation_reason": null,
      "arguments": [
        {
          "name": "id",
          "description": "User ID",
          "type": {
            "kind": "NON_NULL",
            "of_type": {
              "kind": "SCALAR",
              "name": "ID"
            },
            "is_required": true
          },
          "default_value": null
        }
      ],
      "return_type": {
        "kind": "OBJECT",
        "name": "User",
        "description": "A user in the system"
      }
    }
  ],
  "total": 1
}

Type Details

{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "type": {
    "name": "User",
    "kind": "OBJECT",
    "description": "A user in the system",
    "fields": [
      {
        "name": "id",
        "description": "Unique identifier",
        "type": {
          "kind": "NON_NULL",
          "of_type": {
            "kind": "SCALAR",
            "name": "ID"
          },
          "is_required": true
        },
        "deprecated": false,
        "deprecation_reason": null
      },
      {
        "name": "email",
        "description": "User email address",
        "type": {
          "kind": "SCALAR",
          "name": "String"
        },
        "deprecated": false,
        "deprecation_reason": null
      }
    ],
    "interfaces": [],
    "possible_types": null
  }
}

Caching

The server implements in-memory caching with the following characteristics:

• Cache Duration: 5 minutes
• Cache Key: Combination of endpoint URL and authentication method
• Automatic Invalidation: Expired entries are automatically removed
• Performance: Subsequent requests to the same endpoint return cached data instantly

Error Handling

The server provides comprehensive error handling for:

• Network Issues: Connection timeouts, DNS resolution failures
• HTTP Errors: 4xx and 5xx responses from GraphQL endpoints
• GraphQL Errors: Schema validation errors, introspection failures
• Authentication Errors: Invalid credentials, expired tokens
• Validation Errors: Missing required parameters, invalid type names

Development

Build

npm run build

Development Mode

npm run dev

Clean Build

npm run clean
npm run build

Configuration

Default Settings

• Default Endpoint: http://localhost:5555/graphql
• Cache Duration: 5 minutes (300 seconds)
• Timeout: Uses fetch default timeout
• Max Cache Size: No limit (memory permitting)

Environment Variables

Variable	Default	Description
GRAPHQL_DEFAULT_ENDPOINT	http://localhost:5555/graphql	Default GraphQL endpoint
CACHE_DURATION_MS	300000	Cache duration in milliseconds (5 minutes)
ALLOW_MUTATIONS	false	Enable mutation execution (true to enable)

Best Practices

For AI Agents

• Use Detailed Mode: Set detailed: true when you need comprehensive information
• Filter Effectively: Use search patterns to reduce response size
• Cache Awareness: Subsequent calls to the same endpoint will be faster due to caching
• Error Handling: Always check the success field in responses

For Performance

• Specific Searches: Use specific search terms to reduce response size
• Type Filtering: Use the kind parameter when filtering types
• Summary Mode: Use detailed: false for quick overviews
• Endpoint Reuse: Reuse the same endpoint URL to benefit from caching

Troubleshooting

Common Issues

Schema not found

• Verify the GraphQL endpoint URL is correct
• Check if the endpoint requires authentication
• Ensure the endpoint supports introspection queries

Authentication failures

• Verify credentials are correct
• Check if the endpoint expects Basic Auth or Bearer tokens
• Ensure tokens haven't expired

Network timeouts

• Check network connectivity to the GraphQL endpoint
• Verify firewall settings allow outbound connections
• Consider if the GraphQL server is running and responsive

Debug Mode

Enable debug logging by setting the environment variable:

export DEBUG=graphql-introspection:*

License

MIT License - see LICENSE file for details.