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.

referencestelemetry.md

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

OpenTelemetry Integration

Overview

Apollo MCP Server exports metrics and traces using the OpenTelemetry Protocol (OTLP). Telemetry is disabled by default and must be configured to enable export.

Signal Default Destination
Logs Enabled at info stderr (stdio) or stdout (streamable_http), or configured log files
Traces Export disabled Configured OTLP tracing endpoint
Metrics Export disabled Configured OTLP metrics endpoint

Configuration

Quick Start

telemetry:
  exporters:
    metrics:
      otlp:
        endpoint: "http://localhost:4318/v1/metrics"
        protocol: "http/protobuf"
    tracing:
      otlp:
        endpoint: "http://localhost:4318/v1/traces"
        protocol: "http/protobuf"

Full Configuration Reference

Top-Level Telemetry
Option Type Default Description
service_name string "apollo-mcp-server" Service name in telemetry data
version string Current crate version Service version in telemetry data
exporters Exporters null Exporter configuration
Metrics Exporter
Option Type Default Description
otlp.endpoint URL http://localhost:4317 OTLP export endpoint
otlp.protocol string grpc grpc or http/protobuf
otlp.temporality string cumulative cumulative, delta, or lowmemory
otlp.metadata key-value pairs gRPC metadata (only with grpc protocol)
otlp.headers key-value pairs HTTP headers (only with http/protobuf protocol)
export_interval Duration 30s Interval for metric export
omitted_attributes List<String> Metric attributes to omit before export
Tracing Exporter
Option Type Default Description
otlp.endpoint URL http://localhost:4317 OTLP export endpoint
otlp.protocol string grpc grpc or http/protobuf
otlp.metadata key-value pairs gRPC metadata (only with grpc protocol)
otlp.headers key-value pairs HTTP headers (only with http/protobuf protocol)
sampler string always_on always_on, always_off, or 0.0-1.0 percentage
omitted_attributes List<String> Span attributes to omit before export

Production Example

telemetry:
  service_name: "mcp-server-prod"
  version: "1.0.0"
  exporters:
    metrics:
      otlp:
        endpoint: "https://your-metrics-endpoint"
        protocol: "http/protobuf"
      export_interval: 1m
    tracing:
      otlp:
        endpoint: "https://your-traces-endpoint"
        protocol: "http/protobuf"
      sampler: 0.1

Emitted Metrics

Metric Type Description Attributes
apollo.mcp.initialize.count Counter Each initialize request client_name, client_version
apollo.mcp.list_tools.count Counter Each list_tools request
apollo.mcp.get_info.count Counter Each get_info request
apollo.mcp.tool.count Counter Each tool call tool_name, success
apollo.mcp.tool.duration Histogram Tool execution duration (ms) tool_name, success
apollo.mcp.operation.count Counter Each downstream GraphQL operation operation.id, operation.type, success
apollo.mcp.operation.duration Histogram GraphQL operation round-trip (ms) operation.id, operation.type, success

Standard HTTP server metrics are also emitted: http.server.request.duration (histogram), http.server.active_requests (gauge), http.server.request.body.size (histogram), and http.server.response.body.size (histogram).

Emitted Traces

Spans are generated for:

  • HTTP requests to the MCP endpoint (not health checks)
  • MCP handler methods (tools, resources, prompts, initialization)
  • Tool execution with nested spans per tool
  • Downstream GraphQL calls with traceparent, tracestate, and baggage propagation

Key Span Attributes

call_tool span:

Attribute Description
apollo.mcp.tool_name Tool name
apollo.mcp.request_id MCP request ID
apollo.mcp.tool_arguments Tool input (JSON)
apollo.mcp.tool_result Tool output (JSON)

HTTP server span

The span wrapping each request to the MCP endpoint is a SERVER span named {method} {route} (e.g., POST /mcp). Key attributes: http.request.method, url.path, http.response.status_code (integer), apollo.mcp.session_id, server.address, server.port.

GraphQL execute span:

Attribute Description
apollo.mcp.graphql_query GraphQL query sent
apollo.mcp.graphql_response GraphQL response received

Sensitive Data

Tool arguments, results, queries, and responses can contain sensitive data. Omit specific attributes:

telemetry:
  exporters:
    tracing:
      omitted_attributes:
        - tool_arguments
        - tool_result
        - graphql_query
        - graphql_response

Use short attribute names like tool_name, operation_id, tool_arguments, graphql_response.

Trace Context Propagation

MCP requests can carry W3C traceparent, tracestate, and baggage in params._meta over stdio or streamable HTTP. A valid _meta.traceparent becomes the parent of the MCP handler span. Trace context propagates automatically to downstream GraphQL requests.

Dashboard Templates

Apollo provides pre-built dashboard templates at apollographql/apm-templates:

Platform Location
Grafana grafana/
Datadog datadog/

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.