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 <file> -c "<Type.field>" -v "{}"

• Verify the connector executes correctly

Step 5: Test

• Create or update test files under

  /tests/

• Run

  rover connector test

• Ensure full test coverage for each connector

Schema Template

# 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