Connect AI Agents to Your GraphQL API Using MCP and Type-Safe Tool Configuration

Prerequisites: This post assumes familiarity with GraphQL (queries, mutations, schemas) and the basics of MCP (what tools are, how agents call them). If you’re looking for a simpler starting point, see the Apollo MCP Server quickstart guide.

Connecting AI agents to APIs creates a configuration problem: how do you control which operations agents can execute, validate their inputs before runtime, and enforce security boundaries? REST wrappers leave these concerns to application code. GraphQL’s type system handles them at the configuration layer.

Apollo MCP Server provides three patterns for exposing GraphQL operations as MCP tools. The simplest pattern works with any GraphQL API, no Apollo infrastructure required. We recommend starting with Pattern 1 and adding complexity only when you need it.

Pattern 1: Pre-defined operations from files as MCP tools

Works with any GraphQL API. No GraphOS required. Start here.

1# apollo-mcp-server.yaml2graphql:3  endpoint: https://your-api.example.com/graphql4operations:5  source: local6  paths:7    - ./operations/*.graphql

Write your operations:

1# operations/GetUserOrders.graphql2query GetUserOrders($userId: ID!, $limit: Int = 10) {3  user(id: $userId) {4    name5    orders(first: $limit) {6      id7      total8      createdAt9    }10  }11}

Required and optional parameters are determined automatically from GraphQL’s type system:

• Non-null types (ID!, String!) become required parameters
• Nullable types (ID, String) become optional parameters
• Variables with default values ($limit: Int = 10) are optional with the specified default

When to use this pattern:

• You want explicit control over every operation agents can execute
• You’re working with mutations or operations with significant side effects
• You’re using any GraphQL API, regardless of infrastructure

The tradeoff: You must define every operation upfront. For large APIs, this means maintaining many .graphql files. Adding a new capability requires writing, testing, and redeploying.

Pattern 2: Persisted queries from Apollo GraphOS as MCP tools

If you’re already using Apollo GraphOS, you can expose persisted queries as MCP tools. The server fetches operations from GraphOS and converts each into a tool.

1# apollo-mcp-server.yaml2operations:3  source: uplink

This provides safelisting by default. Apollo Router only accepts operations from the manifest, preventing arbitrary query execution.

When to use this pattern:

• Your organization already uses GraphOS with persisted queries
• Safelisting is a hard security requirement
• You want agent capabilities to stay in sync with deployed client applications

The tradeoff: Requires Apollo GraphOS infrastructure. Operations must be published before agents can use them.

Pattern 3: Dynamic operations via MCP introspection tools

Instead of pre-defining operations, you give agents tools to explore the schema and construct operations at runtime.

Apollo MCP Server provides four introspection tools:

When to use this pattern:

• Your schema is self-documenting with descriptive field names
• You cannot predict which operations agents will need
• You want to reduce the overhead of maintaining operation files

The tradeoff: Agents can construct arbitrary queries. This flexibility requires security configuration (covered below).

Security: Controlling query cost and mutation access

GraphQL’s flexibility creates risks when agents construct queries dynamically. GraphQL’s flexibility creates risks when agents construct queries dynamically. Apollo Router’s demand control feature addresses this by assigning a cost to each field and type in an operation, rejecting operations that exceed a configured threshold. You can tune cost calculations with the @cost directive on expensive fields or types and the @listSize directive on list fields — particularly important when agents can’t predict result set sizes.

Mutation mode options

For mutations, Apollo MCP Server controls what agents can execute through a mutation mode setting:

Combining MCP configuration patterns

A common configuration uses pre-defined operations for writes and introspection for reads:

1# apollo-mcp-server.yaml2operations:3  source: local4  paths:5    - ./mutations/*.graphql6introspection:7  execute:8    enabled: true9  search:10    enabled: true11overrides:12  mutation_mode: explicit

This gives you flexible reads with controlled writes. Agents can explore the schema and run ad-hoc queries, but mutations require explicit approval through pre-defined operations.

Why GraphQL for agent APIs

If agents write code to call APIs, why does the data layer matter?

Type-safe validation before execution. When an agent calls REST endpoints, type errors surface at runtime. With GraphQL, the validate tool checks operations against the schema before any data is fetched:

1const validation = await validate({2  operation: `query { user(id: "123") { orders { items { name } } } }`3});4// Returns: "Cannot query field 'name' on type 'OrderItem'."5//          "Did you mean 'productName'?"

Agents can iterate on query construction without making costly API calls for each attempt.

Precise data fetching. REST endpoints return fixed response shapes. An agent wanting user orders must fetch /users/123 and /users/123/orders separately, then correlate results. GraphQL composes these in a single request, returning exactly the fields requested. Smaller payloads mean fewer tokens consumed and less post-processing code.

Schema discovery via semantic search. The search tool finds relevant types and fields:

1search({ terms: ["user", "order", "history"] })2  User.orders(first: Int, after: String): OrderConnection3  Order.createdAt: DateTime4  Order.status: OrderStatus

Agents get a structured path from intent to operation without reading endpoint documentation.

Agents that follow best practices. When agents construct GraphQL operations, they make choices: anonymous vs. named queries, inline values vs. variables, which fields to request. Without guidance, agents default to patterns that work but miss optimizations. Apollo Skills encodes these decisions as reusable knowledge modules. An agent with the graphql-operations skill uses named operations (visible in server logs), variables (enabling query reuse), and includes id fields (enabling cache normalization). These details compound across a codebase. If you’re using Claude Code, Cursor, or GitHub Copilot, install Skills with npx skills add apollographql/skills.

A note on MCP maturity

MCP is early. The protocol continues to evolve, and today’s patterns may change as the ecosystem matures. We’ve designed Apollo MCP Server with this in mind:

• Pattern 1 has no framework lock-in. It’s configuration over your existing GraphQL API.
• The server is open source, so you can fork and adapt as needed.
• We’re tracking protocol changes and will document migration paths.

If you’re evaluating whether to invest in MCP tooling, Pattern 1 offers a low-commitment starting point.

For AI coding tool users: Apollo Skills

MCP Server gives agents the capability to interact with your GraphQL API. Apollo Skills teaches them how to do it well.

Skills are reusable knowledge modules for AI agents, comparable to plugins or npm packages but for AI assistants instead of code. When an agent writes a GraphQL schema, the graphql-schema skill guides it toward intentional nullability and proper list patterns ([Item!]! instead of [Item]). When configuring MCP Server, the apollo-mcp-server skill provides step-by-step workflows and common pitfalls to avoid.

1# Install all Apollo skills2npx skills add apollographql/skills3 4# Or install specific skills5npx skills add apollographql/skills@apollo-mcp-server6npx skills add apollographql/skills@graphql-operations

The CLI detects which tools you’re using (Claude Code, Cursor, GitHub Copilot, and others) and configures them automatically. Once installed, skills activate automatically based on context—for example, when you mention “MCP server configuration” or “GraphQL schema design” in your request, Claude will automatically load the relevant skill.

Skills and MCP Server address different layers of the same problem:

Together, they create a complete workflow: Skills ensure agents write good GraphQL, and MCP Server ensures they write working GraphQL.

Summary

Apollo MCP Server provides three configuration patterns:

1. Pre-defined operations (recommended starting point): Explicit control, works with any GraphQL API

2. Persisted queries: Leverage existing GraphOS infrastructure and safelisting

3. Dynamic introspection: Flexibility with explicit security configuration

GraphQL’s type system provides guarantees about data shape, query validity, and response structure that agents can rely on. Start with Pattern 1, add complexity when you need it.

Apollo MCP Server is open source. Explore the Apollo MCP Server documentation for configuration details, or clone the GitHub repository to try it locally.

Written by

Camille Lawrence

Read more by Camille Lawrence