Index of every page on this site: llms.txt
All skills
apollographql avatar

/apollo-mcp-server

@9dda139 official
by Apollo GraphQLapollographql/skills134 stars
14
Run it yourself

Guide for using Apollo MCP Server to connect AI agents with GraphQL APIs. Use this skill when: (1) setting up or configuring Apollo MCP Server, (2) defining MCP tools from GraphQL operations, (3) using introspection tools (introspect, search, validate, execute, explorer), (4) configuring authentication, CORS, health checks, or telemetry, (5) writing Rhai scripts for request lifecycle hooks, (6) defining MCP prompts, (7) troubleshooting MCP server connectivity or tool execution issues, (8) building MCP Apps for interactive UI experiences, (9) deploying Apollo MCP Server to production.

Use this Skill: https://skilld.dev/gh/apollographql/skills/apollo-mcp-server

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesauth.md

≈1.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Apollo MCP Server Authentication and Authorization

Overview

Apollo MCP Server supports OAuth 2.1 authentication for streamable_http transport. Auth is configured under transport.auth (not at the top level). The stdio transport does not support authentication.

The server validates signed JWT bearer access tokens. Each JWT must contain a kid header, plus exp and sub claims. Opaque tokens are not supported.

Configuration

transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com
    audiences:
      - https://api.example.com
    issuers:
      - "https://auth.example.com"
    allow_any_audience: false
    resource: https://hosted.mcp.server/mcp
    resource_documentation: https://info.mcp.server
    scopes:
      - read
      - write
    scope_mode: require_all
    discovery_timeout: 5s
    discovery_headers:
      User-Agent: apollo-mcp-server
    disable_auth_token_passthrough: false
    tls:
      ca_cert: /path/to/ca-certificate.pem
      danger_accept_invalid_certs: false

Auth Options

Option Type Default Description
servers List<URL> Issuer URLs of upstream OAuth servers, not discovery-document URLs (must support RFC 8414 or OIDC discovery)
audiences List<string> [] Accepted JWT audience values
issuers List<string> [] Allowlist for token issuers. When set, iss must match this list and discovery metadata
allow_any_audience bool false Skip audience validation entirely
resource string Externally available URL of this MCP server
resource_documentation string Link to documentation for this MCP server
scopes List<string> [] Global OAuth scopes. Advertised and enforced per scope_mode. Omitting defaults to an empty list (no global scope requirement)
scope_mode string require_all require_all, require_any, or disabled
disable_auth_token_passthrough bool false Disable automatic propagation of validated token to downstream API
discovery_timeout Duration 5s Timeout for metadata discovery requests
discovery_headers Map<string, string> {} Custom headers for OIDC discovery and JWKS requests
tls.ca_cert string Path to CA certificate (PEM) for private CA or self-signed certs
tls.danger_accept_invalid_certs bool false Accept invalid TLS certificates (development only)

Scope Enforcement

Mode Behavior
require_all Token must have all configured scopes (default)
require_any Token must have at least one scope
disabled Skip global scope check; per-operation requirements still apply

Per-Operation Scope Requirements

Declare additional scopes per tool using overrides.required_scopes:

overrides:
  required_scopes:
    GetUser:
      - user:read
    DeleteUser:
      - user:write
      - admin

A flat list requires all scopes. Nested lists express alternatives (inner = AND, outer = OR):

overrides:
  required_scopes:
    UpdateUser:
      - [user:write, tenant:admin]
      - [admin]

When a token lacks required scopes, the server returns 403 Forbidden with a WWW-Authenticate header. Per-operation requirements add to (not replace) the global requirement.

Skipping Token Validation

Allow specific requests to bypass token validation when no Authorization header is present:

transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com
    skip_token_validation:
      methods:
        - initialize
        - notifications/initialized
        - tools/list
      tools:
        - SearchDocs
      headers:
        - x-api-key
List Matches on Notes
methods JSON-RPC method name tools/call cannot be listed here (rejected at startup)
tools Tool name in tools/call Specific tools reachable without a token
headers HTTP header name Skips validation for any method when header is present

Security: A request with a listed header skips token validation for all methods and tools. Ensure something downstream validates the header value. Also list the header in forward_headers so it reaches your API.

A request that carries an Authorization header is always validated, even if it matches a skip rule. An expired token on a public tool returns 401, while no token succeeds.

Rate Limiting

Rate limiting protects against brute-force authentication attempts. Enabled by default.

Option Type Default Description
rate_limit.enabled bool true Rate limit bearer credentials that fail authentication
rate_limit.requests_per_second number 10 Sustained requests per second for each failing credential
rate_limit.burst number 50 Burst requests before sustained rate applies
transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com
    rate_limit:
      enabled: true
      requests_per_second: 10
      burst: 50

Set enabled: false when requests are already rate limited before reaching the server.

HTTP Error Responses

Status When
401 Unauthorized Token missing, malformed, expired, bad signature, or fails audience/issuer check
403 Forbidden Token valid but lacks required scopes

Both responses include a WWW-Authenticate header with resource_metadata URL and scope parameters.

Discovery Compatibility

The server tries discovery URLs in order:

  1. RFC 8414 path-insertion (/.well-known/oauth-authorization-server/<path>)
  2. OIDC Discovery path-insertion (/.well-known/openid-configuration/<path>)
  3. OIDC Discovery path-appending (/<path>/.well-known/openid-configuration)

The first parseable metadata document is used.

JWKS Caching

  • Cached per issuer, entries stay fresh for 10 minutes
  • Known kid values served from stale cache during outages
  • Per-issuer rate limiting prevents fabricated kid attacks

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert23d5 checks · Risk HIGH
  • Gen Agent Trust Hub23d

    This skill provides a comprehensive guide for using the Apollo MCP Server. It includes official installation commands that download and execute scripts from the vendor's domain. The skill also processes external GraphQL data, such as schemas and operations, which presents a surface for indirect prompt injection if these sources are attacker-controlled. Additionally, it documents the use of Rhai scripting for runtime customization of server behavior.

  • Socket23d

    No alerts

  • Snyk23d

    Risk: LOW · No issues

  • Runlayer8mo

    2/4 files flagged

  • ZeroLeaks7mo

    1 finding · Score: 82/100

Signed by skilld at 9dda139. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 4 weeks ago
What it can do
Runs commands
compatibility
Works with Claude Code, Claude Desktop, Cursor.
metadata
{
  "author": "apollographql",
  "version": "1.3.0"
}
All 1 allowed tools
Bash(rover:*) Bash(npx:*) Read Write Edit Glob Grep
  • MCP
  • API
  • graphql
  • apollo
  • introspection
  • schema
  • claude
  • cursor
  • authentication

README badge

README badge for apollographql/skills/apollo-mcp-server

Exposes GraphQL operations as MCP tools, allowing AI agents to query and mutate GraphQL APIs through the Model Context Protocol. Includes introspection tools (search, validate, execute) and supports operation files, GraphOS collections, and persisted queries with configurable authentication and mutation controls.

Generated from the current SKILL.md.

What transport types does Apollo MCP Server support?
Apollo MCP Server supports streamable_http (recommended for remote and multi-client deployments) and stdio (for clients that launch the server directly). Streamable_http defaults to address 127.0.0.1 and port 8000.
Can I use this with Claude Desktop and Claude Code?
Yes. Apollo MCP Server is compatible with Claude Desktop, Claude Code, and Cursor. Configuration differs slightly: Claude Desktop uses claude_desktop_config.json, while Claude Code uses .mcp.json or the claude mcp add command.
How do I define custom tools from GraphQL operations?
Create GraphQL operation files in a directory (one operation per file) and configure the operations source as local with the directory path. Each named operation automatically becomes an MCP tool. You can also use GraphOS Studio collections or persisted query manifests.
What security settings should I enable for production?
Set mutation_mode to explicit or none (default), use headers configuration for API keys, enable health checks, disable introspection tools, and authenticate requests with Bearer tokens or OAuth. Use persisted queries instead of ad-hoc operations.
What are the four built-in introspection tools?
introspect (explore schema types), search (find types in schema), validate (check operation validity), and execute (run ad-hoc GraphQL operations). All four are disabled by default and must be explicitly enabled in config.yaml.

Generated from the current SKILL.md. These answers refresh after source changes.