Subchapter 6.2
references/tools.mdMarkdown6 KBView on GitHub
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.
Explore schema types in detail with configurable depth.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
type | String | required | Type name to introspect |
depth | Int | 1 | Recursion depth for related types |
minify | Boolean | false | Use compact notation |
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 typedepth: 2 - Requested type + directly referenced typesdepth: 3 - Two levels of related typesFind types in the schema matching a query.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
query | String | required | Search term |
leafDepth | Int | 1 | Depth for leaf type expansion |
minify | Boolean | false | Use compact notation |
Config Options:
| Option | Default | Description |
|---|---|---|
index_memory_bytes | 50000000 | Memory budget for the search index |
leaf_depth | 1 | Default leaf type expansion depth |
Behavior:
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)Check if a GraphQL operation is valid against the schema.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
operation | String | required | GraphQL operation to validate |
Validates:
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! }Run ad-hoc GraphQL operations against the endpoint.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
operation | String | required | GraphQL operation |
variables | Object | {} | Operation variables |
Mutation Mode:
Behavior depends on overrides.mutation_mode configuration:
| Mode | Query | Mutation |
|---|---|---|
all | Execute | Execute |
explicit | Execute | Require confirmation |
none | Execute | Block |
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" } }
)Compact notation reduces token usage by 40-60%. Enable globally or per-request.
| Symbol | Meaning |
|---|---|
T | type |
I | input |
E | enum |
U | union |
F | interface |
| Symbol | Meaning |
|---|---|
s | String |
i | Int |
f | Float |
b | Boolean |
d | ID |
| Symbol | Meaning |
|---|---|
| ! | Non-null (required) |
| [] | List |
| [!] | List of non-null |
| []! | Non-null list |
| [!]! | Non-null list of non-null |
@D | Deprecated |
<> | Implements |
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!] }Each GraphQL operation becomes an MCP tool with:
GetUser, CreateProduct)# Tool name: GetUserById
query GetUserById($id: ID!) {
user(id: $id) { id name }
}
# Tool name: CreateProduct
mutation CreateProduct($input: ProductInput!) {
createProduct(input: $input) { id }
}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.