{"id":"20896ffe-c5b0-4d86-9105-ca11e7728ec4","shortId":"3RJMQn","kind":"skill","title":"apollo-mcp-server","tagline":"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), (4) troubleshooti","description":"# Apollo MCP Server Guide\n\nApollo MCP Server exposes GraphQL operations as MCP tools, enabling AI agents to interact with GraphQL APIs through the Model Context Protocol.\n\n## Quick Start\n\n### Step 1: Install\n\n```bash\n# Linux / MacOS\ncurl -sSL https://mcp.apollo.dev/download/nix/latest | sh\n\n# Windows\niwr 'https://mcp.apollo.dev/download/win/latest' | iex\n```\n\n### Step 2: Configure\n\nCreate `config.yaml` in your project root:\n\n```yaml\n# config.yaml\ntransport:\n  type: streamable_http\nschema:\n  source: local\n  path: ./schema.graphql\noperations:\n  source: local\n  paths:\n    - ./operations/\nintrospection:\n  introspect:\n    enabled: true\n  search:\n    enabled: true\n  validate:\n    enabled: true\n  execute:\n    enabled: true\n```\n\nStart the server:\n```bash\napollo-mcp-server ./config.yaml\n```\n\nThe MCP endpoint is available at `http://127.0.0.1:8000/mcp` (streamable_http defaults: address `127.0.0.1`, port `8000`). The GraphQL endpoint defaults to `http://localhost:4000/` — override with the `endpoint` key if your API runs elsewhere.\n\n### Step 3: Connect\n\nAdd to your MCP client configuration:\n\n**Streamable HTTP (recommended):**\n\nClaude Desktop (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"graphql-api\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-remote\", \"http://127.0.0.1:8000/mcp\"]\n    }\n  }\n}\n```\n\nClaude Code:\n```bash\nclaude mcp add graphql-api -- npx mcp-remote http://127.0.0.1:8000/mcp\n```\n\n**Stdio (client launches the server directly):**\n\nClaude Desktop (`claude_desktop_config.json`) or Claude Code (`.mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"graphql-api\": {\n      \"command\": \"./apollo-mcp-server\",\n      \"args\": [\"./config.yaml\"]\n    }\n  }\n}\n```\n\n## Built-in Tools\n\nApollo MCP Server provides four introspection tools:\n\n| Tool | Purpose | When to Use |\n|------|---------|-------------|\n| `introspect` | Explore schema types in detail | Need type definitions, fields, relationships |\n| `search` | Find types in schema | Looking for specific types or fields |\n| `validate` | Check operation validity | Before executing operations |\n| `execute` | Run ad-hoc GraphQL operations | Testing or one-off queries |\n\n## Defining Custom Tools\n\nMCP tools are created from GraphQL operations. Three methods:\n\n### 1. Operation Files (Recommended)\n\n```yaml\noperations:\n  source: local\n  paths:\n    - ./operations/\n```\n\nEach file must contain exactly one operation. Each named operation becomes an MCP tool.\n\n```graphql\n# operations/GetUser.graphql\nquery GetUser($id: ID!) {\n  user(id: $id) {\n    id\n    name\n    email\n  }\n}\n```\n\n```graphql\n# operations/CreateUser.graphql\nmutation CreateUser($input: CreateUserInput!) {\n  createUser(input: $input) {\n    id\n    name\n  }\n}\n```\n\n### 2. Operation Collections\n\n```yaml\noperations:\n  source: collection\n  id: your-collection-id\n```\n\nUse GraphOS Studio to manage operations collaboratively.\n\n### 3. Persisted Queries\n\n```yaml\noperations:\n  source: manifest\n  path: ./persisted-query-manifest.json\n```\n\nFor production environments with pre-approved operations.\n\n## Reference Files\n\nDetailed documentation for specific topics:\n\n- [Tools](references/tools.md) - Introspection tools and minify notation\n- [Configuration](references/configuration.md) - All configuration options\n- [Troubleshooting](references/troubleshooting.md) - Common issues and solutions\n\n## Key Rules\n\n### Security\n\n- **Never expose sensitive operations** without authentication\n- Use `headers` configuration for API keys and tokens\n- Disable introspection tools in production (they are disabled by default)\n- Set `overrides.mutation_mode: explicit` to require confirmation for mutations\n\n### Authentication\n\n```yaml\n# Static header\nheaders:\n  Authorization: \"Bearer ${env.API_TOKEN}\"\n\n# Dynamic header forwarding\nforward_headers:\n  - x-forwarded-token\n\n# OAuth (streamable_http transport)\ntransport:\n  type: streamable_http\n  auth:\n    servers:\n      - https://auth.example.com/.well-known/openid-configuration\n    audiences:\n      - https://api.example.com\n```\n\n### Token Optimization\n\nEnable minification to reduce token usage:\n\n```yaml\nintrospection:\n  introspect:\n    minify: true\n  search:\n    minify: true\n```\n\nMinified output uses compact notation:\n- **T** = type, **I** = input, **E** = enum\n- **s** = String, **i** = Int, **b** = Boolean, **f** = Float, **d** = ID\n- **!** = required, **[]** = list\n\n### Mutations\n\nControl mutation behavior via the `overrides` section:\n\n```yaml\noverrides:\n  mutation_mode: all       # Execute mutations directly\n  # mutation_mode: explicit  # Require explicit confirmation\n  # mutation_mode: none      # Block all mutations (default)\n```\n\n## Common Patterns\n\n### GraphOS Cloud Schema\n\n```yaml\n# schema.source defaults to uplink — can be omitted when graphos is configured\ngraphos:\n  apollo_key: ${env.APOLLO_KEY}\n  apollo_graph_ref: my-graph@production\n```\n\n### Local Development\n\n```yaml\ntransport:\n  type: streamable_http\nschema:\n  source: local\n  path: ./schema.graphql\nintrospection:\n  introspect:\n    enabled: true\n  search:\n    enabled: true\n  validate:\n    enabled: true\n  execute:\n    enabled: true\noverrides:\n  mutation_mode: all\n```\n\n### Production Setup\n\n```yaml\ntransport:\n  type: streamable_http\nendpoint: https://api.production.com/graphql\noperations:\n  source: manifest\n  path: ./persisted-query-manifest.json\ngraphos:\n  apollo_key: ${env.APOLLO_KEY}\n  apollo_graph_ref: ${env.APOLLO_GRAPH_REF}\nheaders:\n  Authorization: \"Bearer ${env.API_TOKEN}\"\nhealth_check:\n  enabled: true\n```\n\n### Docker\n\n```yaml\ntransport:\n  type: streamable_http\n  address: 0.0.0.0\n  port: 8000\nendpoint: ${env.GRAPHQL_ENDPOINT}\ngraphos:\n  apollo_key: ${env.APOLLO_KEY}\n  apollo_graph_ref: ${env.APOLLO_GRAPH_REF}\nhealth_check:\n  enabled: true\n```\n\n## Ground Rules\n\n- ALWAYS configure authentication before exposing to AI agents\n- ALWAYS use `mutation_mode: explicit` or `mutation_mode: none` in shared environments\n- NEVER expose introspection tools with write access to production data\n- PREFER operation files over ad-hoc execute for predictable behavior\n- PREFER streamable_http transport for remote and multi-client deployments\n- USE stdio only when the MCP client launches the server process directly\n- USE GraphOS Studio collections for team collaboration","tags":["apollo","mcp","server","skills","apollographql","agent-skills","graphql"],"capabilities":["skill","source-apollographql","skill-apollo-mcp-server","topic-agent-skills","topic-apollo","topic-graphql"],"categories":["skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/apollographql/skills/apollo-mcp-server","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add apollographql/skills","source_repo":"https://github.com/apollographql/skills","install_from":"skills.sh"}},"qualityScore":"0.736","qualityRationale":"deterministic score 0.74 from registry signals: · indexed on github topic:agent-skills · official publisher · 71 github stars · SKILL.md body (6,235 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:57:01.881Z","embedding":null,"createdAt":"2026-04-18T20:32:21.976Z","updatedAt":"2026-05-18T18:57:01.881Z","lastSeenAt":"2026-05-18T18:57:01.881Z","tsv":"'/.well-known/openid-configuration':481 '/apollo-mcp-server':234 '/config.yaml':139,236 '/download/nix/latest':85 '/download/win/latest''':91 '/graphql':620 '/operations':117,316 '/persisted-query-manifest.json':381,625 '/schema.graphql':112,592 '0.0.0.0':653 '1':22,76,307 '127.0.0.1':146,152,198,213 '2':30,94,354 '3':37,173,373 '4':45 '4000':161 '8000':154,655 '8000/mcp':147,199,214 'access':702 'ad':285,711 'ad-hoc':284,710 'add':175,205 'address':151,652 'agent':14,62,683 'ai':13,61,682 'alway':676,684 'api':17,67,169,191,208,232,428 'api.example.com':483 'api.production.com':619 'api.production.com/graphql':618 'apollo':2,8,27,47,51,136,241,570,574,627,631,660,664 'apollo-mcp-serv':1,135 'approv':388 'arg':194,235 'audienc':482 'auth':477 'auth.example.com':480 'auth.example.com/.well-known/openid-configuration':479 'authent':423,451,678 'author':456,638 'avail':144 'b':515 'bash':78,134,202 'bearer':457,639 'becom':327 'behavior':526,716 'block':548 'boolean':516 'built':238 'built-in':237 'check':276,643,671 'claud':184,200,203,221,225 'claude_desktop_config.json':186,223 'client':179,216,726,734 'cloud':555 'code':201,226 'collabor':372,746 'collect':356,360,364,743 'command':192,233 'common':411,552 'compact':503 'config.yaml':97,103 'configur':26,95,180,404,407,426,568,677 'confirm':448,544 'connect':12,174 'contain':320 'context':71 'control':524 'creat':96,301 'createus':346,349 'createuserinput':348 'curl':81 'custom':296 'd':519 'data':705 'default':150,158,441,551,559 'defin':31,295 'definit':261 'deploy':727 'desktop':185,222 'detail':258,392 'develop':582 'direct':220,538,739 'disabl':432,439 'docker':646 'document':393 'dynam':460 'e':509 'elsewher':171 'email':342 'enabl':60,120,123,126,129,486,595,598,601,604,644,672 'endpoint':142,157,165,617,656,658 'enum':510 'env.api':458,640 'env.apollo':572,629,634,662,667 'env.graphql':657 'environ':384,695 'exact':321 'execut':44,128,280,282,536,603,713 'explicit':445,541,543,688 'explor':254 'expos':54,419,680,697 'f':517 'field':262,274 'file':309,318,391,708 'find':265 'float':518 'forward':462,463,467 'four':245 'getus':334 'graph':575,579,632,635,665,668 'grapho':367,554,566,569,626,659,741 'graphql':16,35,55,66,156,190,207,231,287,303,331,343 'graphql-api':189,206,230 'ground':674 'guid':5,50 'header':425,454,455,461,464,637 'health':642,670 'hoc':286,712 'http':107,149,182,471,476,587,616,651,719 'id':335,336,338,339,340,352,361,365,520 'iex':92 'input':347,350,351,508 'instal':77 'int':514 'interact':64 'introspect':39,41,118,119,246,253,399,433,493,494,593,594,698 'issu':412 'iwr':88 'json':187,228 'key':166,415,429,571,573,628,630,661,663 'launch':217,735 'linux':79 'list':522 'local':110,115,314,581,590 'localhost':160 'look':269 'maco':80 'manag':370 'manifest':379,623 'mcp':3,9,28,32,48,52,58,137,141,178,196,204,211,242,298,329,733 'mcp-remot':195,210 'mcp.apollo.dev':84,90 'mcp.apollo.dev/download/nix/latest':83 'mcp.apollo.dev/download/win/latest''':89 'mcp.json':227 'mcpserver':188,229 'method':306 'minif':487 'minifi':402,495,498,500 'mode':444,534,540,546,608,687,691 'model':70 'multi':725 'multi-cli':724 'must':319 'mutat':345,450,523,525,533,537,539,545,550,607,686,690 'my-graph':577 'name':325,341,353 'need':259 'never':418,696 'none':547,692 'notat':403,504 'npx':193,209 'oauth':469 'omit':564 'one':292,322 'one-off':291 'oper':36,56,113,277,281,288,304,308,312,323,326,355,358,371,377,389,421,621,707 'operations/createuser.graphql':344 'operations/getuser.graphql':332 'optim':485 'option':408 'output':501 'overrid':162,529,532,606 'overrides.mutation':443 'path':111,116,315,380,591,624 'pattern':553 'persist':374 'port':153,654 'pre':387 'pre-approv':386 'predict':715 'prefer':706,717 'process':738 'product':383,436,580,610,704 'project':100 'protocol':72 'provid':244 'purpos':249 'queri':294,333,375 'quick':73 'recommend':183,310 'reduc':489 'ref':576,633,636,666,669 'refer':390 'references/configuration.md':405 'references/tools.md':398 'references/troubleshooting.md':410 'relationship':263 'remot':197,212,722 'requir':447,521,542 'root':101 'rule':416,675 'run':170,283 'schema':108,255,268,556,588 'schema.source':558 'search':42,122,264,497,597 'section':530 'secur':417 'sensit':420 'server':4,10,29,49,53,133,138,219,243,478,737 'set':23,442 'setup':611 'sh':86 'share':694 'skill':20 'skill-apollo-mcp-server' 'solut':414 'sourc':109,114,313,359,378,589,622 'source-apollographql' 'specif':271,395 'ssl':82 'start':74,131 'static':453 'stdio':215,729 'step':75,93,172 'streamabl':106,148,181,470,475,586,615,650,718 'string':512 'studio':368,742 'team':745 'test':289 'three':305 'token':431,459,468,484,490,641 'tool':33,40,59,240,247,248,297,299,330,397,400,434,699 'topic':396 'topic-agent-skills' 'topic-apollo' 'topic-graphql' 'transport':104,472,473,584,613,648,720 'troubleshoot':409 'troubleshooti':46 'true':121,124,127,130,496,499,596,599,602,605,645,673 'type':105,256,260,266,272,474,506,585,614,649 'uplink':561 'usag':491 'use':7,18,38,252,366,424,502,685,728,740 'user':337 'valid':43,125,275,278,600 'via':527 'window':87 'without':422 'write':701 'x':466 'x-forwarded-token':465 'yaml':102,311,357,376,452,492,531,557,583,612,647 'your-collection-id':362","prices":[{"id":"68d483f8-e1c6-4abf-ab35-23c0f0b0027a","listingId":"20896ffe-c5b0-4d86-9105-ca11e7728ec4","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"apollographql","category":"skills","install_from":"skills.sh"},"createdAt":"2026-04-18T20:32:21.976Z"}],"sources":[{"listingId":"20896ffe-c5b0-4d86-9105-ca11e7728ec4","source":"github","sourceId":"apollographql/skills/apollo-mcp-server","sourceUrl":"https://github.com/apollographql/skills/tree/main/skills/apollo-mcp-server","isPrimary":false,"firstSeenAt":"2026-04-18T22:17:23.139Z","lastSeenAt":"2026-05-18T18:57:01.881Z"},{"listingId":"20896ffe-c5b0-4d86-9105-ca11e7728ec4","source":"skills_sh","sourceId":"apollographql/skills/apollo-mcp-server","sourceUrl":"https://skills.sh/apollographql/skills/apollo-mcp-server","isPrimary":true,"firstSeenAt":"2026-04-18T20:32:21.976Z","lastSeenAt":"2026-05-07T22:40:32.294Z"}],"details":{"listingId":"20896ffe-c5b0-4d86-9105-ca11e7728ec4","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"apollographql","slug":"apollo-mcp-server","github":{"repo":"apollographql/skills","stars":71,"topics":["agent-skills","apollo","graphql"],"license":"mit","html_url":"https://github.com/apollographql/skills","pushed_at":"2026-05-14T17:14:05Z","description":"Apollo GraphQL Agent Skills","skill_md_sha":"e3544e8e93ccaef68adc050ded39737bc7303003","skill_md_path":"skills/apollo-mcp-server/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/apollographql/skills/tree/main/skills/apollo-mcp-server"},"layout":"multi","source":"github","category":"skills","frontmatter":{"name":"apollo-mcp-server","license":"MIT","description":"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), (4) troubleshooting MCP server connectivity or tool execution issues.","compatibility":"Works with Claude Code, Claude Desktop, Cursor."},"skills_sh_url":"https://skills.sh/apollographql/skills/apollo-mcp-server"},"updatedAt":"2026-05-18T18:57:01.881Z"}}