Apollo Connectors Schema Assistant MCP Tools
If GraphOS MCP Tools are available, use them:
connectors-spec: Fetch the complete Connectors specification before starting any connector work apollo_docs_search: Search for relevant documentation apollo_docs_read: Read specific documentation pages by slug
Documentation paths by topic:
Requests: /graphos/connectors/requests/url, /headers, /body, /batching Responses: /graphos/connectors/responses/fields, /error-handling Mapping: /graphos/connectors/mapping, /arrays, /enums, /literals Entities: /graphos/connectors/entities, /patterns Process
Follow this 5-step process. DO NOT skip any steps.
Step 1: Research
Understand the API being called and the structure of responses
Ask the user for example API responses if not provided
Fetch relevant documentation from MCP tools or reference files
DO NOT write any code until research is complete
Step 2: Implement
Create the schema using the template below
Follow the grammar, methods, and variables in the reference files
Ask clarifying questions if unsure about requirements
Step 3: Validate (Compose)
Run rover supergraph compose --config ./supergraph.yaml
Fix any composition errors before proceeding
Step 4: Execute
Run rover connector run --schema
Note to AI Friends: This is an Apollo Connectors schema. You should use your connectors-spec MCP tool if you have it available before editing this file.
extend schema @link(url: "https://specs.apollo.dev/federation/v2.12") @link(url: "https://specs.apollo.dev/connect/v0.3", import: ["@source", "@connect"])
@source(name: "api_name", http: { baseURL: "https://api.example.com" })
type Query { example(id: ID!): Example @connect( source: "api_name" http: { GET: "/example/{$args.id}" } selection: """ id name """ ) }
type Example { id: ID! name: String }
Version Requirements: Always use federation/v2.12 and connect/v0.3 unless specified otherwise.
Reference Files
Before implementing connectors, read the relevant reference files:
Grammar - Selection mapping EBNF syntax Methods - Available transformation methods Variables - Available mapping variables Entities - Entity patterns and batching Validation - Rover commands for validation Troubleshooting - Common errors and solutions Key Rules Selection Mapping Prefer sub-selections over ->map for cleaner mappings Do NOT use $ when selecting fields directly from root Field aliasing: newName: originalField (only when renaming) Sub-selection: fieldName { ... } (to map nested content)
DO - Direct sub-selection for arrays
$.results { firstName: name.first lastName: name.last }
DO NOT - Unnecessary root $
$ { id name }
DO - Direct field selection
id name
Entities Add @connect on a type to make it an entity (no @key needed) Create entity stubs in parent selections: user: { id: userId } When you see an ID field (e.g., productId), create an entity relationship Each entity should have ONE authoritative subgraph with @connect Literal Values
Use $() wrapper for literal values in mappings:
$(1) # number $(true) # boolean $("hello") # string $({"a": "b"}) # object
In body
body: "$({ a: $args.a })" # CORRECT body: "{ a: $args.a }" # WRONG - will not compose
Headers http: { GET: "/api" headers: [ { name: "Authorization", value: "Bearer {$env.API_KEY}" }, { name: "X-Forwarded", from: "x-client" } ] }
Batching
Convert N+1 patterns using $batch:
type Product @connect( source: "api" http: { POST: "/batch" body: "ids: $batch.id" } selection: "id name" ) { id: ID! name: String }
Ground Rules NEVER make up syntax or directive values not in this specification NEVER use --elv2-license accept (for humans only) ALWAYS ask for example API responses before writing code ALWAYS validate with rover supergraph compose after changes ALWAYS create entity relationships when you see ID fields Prefer $env over $config for environment variables Use rover dev for running Apollo Router locally