/apollo-mcp-server

Apollo MCP Server Tools Reference

Table of Contents

• Introspection Tools
  • introspect
  • search
  • validate
  • execute
• Minify Notation
• Custom Tools

Introspection Tools

Apollo MCP Server provides four built-in tools for schema exploration and operation execution. All tools are disabled by default and must be enabled in configuration.

Each introspection tool supports an optional hint config option for providing custom instructions to the AI agent about when and how to use the tool.

introspect

Explore schema types in detail with configurable depth.

Parameters:

Examples:

# Basic type introspection
introspect(type: "User")

# Deep introspection with related types
introspect(type: "User", depth: 3)

# Minified output for token efficiency
introspect(type: "User", minify: true)

Output (normal):

type User {
  id: ID!
  name: String!
  email: String
  posts: [Post!]!
  createdAt: DateTime!
}

Output (minified):

T User { id:d! name:s! email:s posts:[Post!]! createdAt:DateTime! }

Depth Behavior:

• depth: 1 - Only the requested type
• depth: 2 - Requested type + directly referenced types
• depth: 3 - Two levels of related types
• Maximum recommended: 5

search

Find types in the schema matching a query.

Parameters:

Config Options:

Behavior:

• Returns maximum 5 matching results
• Searches type names, field names, and descriptions
• Case-insensitive matching

Examples:

# Find user-related types
search(query: "user")

# Search with expanded leaf types
search(query: "product", leafDepth: 2)

Output:

Found 3 types matching "user":
- User (type)
- UserInput (input)
- UserConnection (type)

validate

Check if a GraphQL operation is valid against the schema.

Parameters:

Validates:

• Syntax correctness
• Schema compliance (fields exist, types match)
• Variable definitions
• Fragment validity

Examples:

validate(operation: """
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      nonExistentField
    }
  }
""")

Output (error):

Validation failed:
- Field "nonExistentField" not found on type "User"

Output (success):

Operation is valid.
Variables required: { id: ID! }

execute

Run ad-hoc GraphQL operations against the endpoint.

Parameters:

Mutation Mode:

Behavior depends on overrides.mutation_mode configuration:

Examples:

# Query execution
execute(
  operation: "query { users { id name } }"
)

# With variables
execute(
  operation: """
    query GetUser($id: ID!) {
      user(id: $id) { id name }
    }
  """,
  variables: { id: "123" }
)

# Mutation (requires appropriate mutation_mode)
execute(
  operation: """
    mutation CreateUser($input: CreateUserInput!) {
      createUser(input: $input) { id }
    }
  """,
  variables: { input: { name: "Alice", email: "alice@example.com" } }
)

Minify Notation

Compact notation reduces token usage by 40-60%. Enable globally or per-request.

Type Abbreviations

Scalar Abbreviations

Modifiers

Examples

Normal:

type Product {
  id: ID!
  name: String!
  price: Float!
  description: String
  tags: [String!]!
  variants: [ProductVariant!]
}

Minified:

T Product { id:d! name:s! price:f! description:s tags:[s!]! variants:[ProductVariant!] }

Custom Tools

Each GraphQL operation becomes an MCP tool with:

• Tool name: Operation name (e.g., GetUser, CreateProduct)
• Parameters: Operation variables become tool parameters
• Description: Generated from operation or custom via directive

Tool Naming

# Tool name: GetUserById
query GetUserById($id: ID!) {
  user(id: $id) { id name }
}

# Tool name: CreateProduct
mutation CreateProduct($input: ProductInput!) {
  createProduct(input: $input) { id }
}

Adding Descriptions

Use comments for tool descriptions:

# Fetches a user by their unique identifier.
# Returns user profile including name and email.
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

The comment becomes the MCP tool description, helping AI agents understand when to use each tool.