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.

referenceserror-handling.md

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

Error handling

Overview

Apollo MCP Server follows the MCP error model, which distinguishes between protocol errors and tool execution errors. Understanding this distinction is essential for building reliable MCP clients and monitoring the server in production.

Protocol vs tool errors

Protocol errors

Protocol errors indicate that the request itself is malformed or unsupported. Examples include calling an unknown tool or sending an invalid JSON-RPC payload. The server returns a JSON-RPC error response with a numeric code and a message:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unknown tool: NonExistentTool"
  }
}

The tool did not run. Surface these failures directly in the application.

Tool execution errors

Tool execution errors indicate that the request was valid and the tool ran, but execution failed. The server returns a successful JSON-RPC response with isError: true in the result:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "content": [
      { "type": "text", "text": "..." }
    ]
  }
}

Pass tool failures back to the LLM for recovery rather than surfacing them as application errors.

HTTP status codes

For streamable_http transport, the HTTP status code reflects the transport layer, not the outcome of a tool call.

Status Meaning
2xx MCP request accepted. Inspect the JSON-RPC response body.
401 Authentication failure (missing, malformed, or expired token)
403 Token valid but lacks required scopes
4xx / 5xx Request rejected before reaching the tool handler

A tool that fails returns HTTP 200 OK with isError: true in the JSON-RPC result. Do not rely on HTTP status to determine tool success.

GraphQL errors as tool errors

When the upstream GraphQL response includes a non-null errors field, Apollo MCP Server returns a tool execution error. This applies to both fully failed responses (data: null with errors) and partial successes (some data alongside errors). In both cases, isError is true.

With structured content

When overrides.enable_output_schema: true is configured and the client supports structured content, the server returns the GraphQL response in structuredContent:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "data": null,
      "errors": [
        {
          "message": "Cannot query field 'unknownField' on type 'User'",
          "path": ["user"],
          "extensions": { "code": "GRAPHQL_VALIDATION_FAILED" }
        }
      ]
    },
    "content": [
      { "type": "text", "text": "..." }
    ]
  }
}

Parse structuredContent.errors for the standard GraphQL error array, including any extensions your GraphQL server attaches.

For successful GraphQL responses, the same envelope is returned with isError: false and the GraphQL response body in structuredContent.

Without structured content

When structured content is not enabled or the client negotiates an older MCP protocol version, parse the serialized GraphQL response from the text content instead.

Private fields

When an operation uses @private fields, Apollo MCP Server filters those fields out of structuredContent. The full GraphQL response is preserved in the response metadata.

Other tool errors

Some failures occur before the GraphQL request is sent. The server returns these as tool execution errors (isError: true) with a plain text message in content:

  • Tool input does not match the operation's input schema
  • Network or DNS failure reaching the GraphQL endpoint
  • GraphQL endpoint returned a body that is not valid JSON

Recommended error handling flow

  1. Use a spec-compliant MCP client library.
  2. Check for a JSON-RPC error response. This is a protocol failure. The tool did not run.
  3. If the response is a successful result, check result.isError:
    • If true, parse result.structuredContent.errors for GraphQL errors when structured content is present. Fall back to result.content for serialized GraphQL responses and plain text failure messages.
    • If false, the tool succeeded. Read data from structuredContent or content.

Monitoring

Apollo MCP Server records tool and operation outcomes in emitted metrics with a success attribute. Any tool call that returns isError: true is marked as success=false, including calls that return GraphQL errors. Alert on tool failure rates without parsing response bodies.

Metric Attribute Value
apollo.mcp.tool.count success false for any isError: true
apollo.mcp.operation.count success false for GraphQL errors

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.