Building a Secure AI Agent API Stack with GraphQL, Apollo Skills, and MCP Server

AI agents need access to your APIs. The question is how to provide that access without creating a maintenance burden, security risk, or pile of low-quality generated code.

Most teams start with the obvious approach: wrap existing REST endpoints and expose them to agents. This works initially. Then the problems emerge. Agents construct malformed requests. They call endpoints in inefficient sequences. They generate code that works but ignores your team’s conventions. Each agent session requires the same corrections, and the corrections do not persist.

The underlying issue is architectural. REST wrappers give agents access to your APIs but provide no structure for how to use them well. Agents lack three things: a typed contract they can validate against, knowledge of your patterns and conventions, and controlled capabilities with security boundaries.

GraphQL, Apollo Skills, and Apollo MCP Server address these three gaps as complementary layers of a complete agent-API stack.

The Three-Layer Architecture for Secure AI Agent Access to APIs

Each layer addresses a distinct concern. Understanding what each layer does (and does not do) helps you decide where to invest.

These layers are independent. You can adopt one without the others. But they compound when used together.

Layer 1: GraphQL as the data contract for AI agents

REST APIs describe endpoints. GraphQL describes data.

This distinction matters for agents. When an agent constructs a REST request, correctness is verified at runtime. A typo in a field name, a missing parameter, a malformed payload: these surface only when the request executes. Agents iterate through trial and error, making API calls until something works.

GraphQL moves validation earlier. The schema defines every type, field, and argument. Agents can check an operation against the schema before execution. Invalid field? The schema says so. Wrong argument type? Caught before any data is fetched.

1# Agent constructs this query2query GetUser($id: ID!) {3  user(id: $id) {4    name5    orders { items { name } }  # Error: 'name' doesn't exist on OrderItem6  }7}8 9# Schema validation returns:10# "Cannot query field 'name' on type 'OrderItem'. Did you mean 'productName'?"

The agent can fix the query and try again without consuming API resources on failed requests.

GraphQL also solves the over-fetching problem. REST endpoints return fixed response shapes. An agent wanting user data and order history makes two requests, receives fields it does not need, and correlates the results in code. GraphQL composes both in a single request, returning exactly the requested fields. Smaller payloads mean fewer tokens consumed in agent context windows and less post-processing code.

When to adopt this layer: You have REST APIs that agents will query repeatedly. You want validation before execution. You want to reduce payload sizes and agent-side data manipulation.

Layer 2: Apollo Skills as the knowledge layer for improving AI-generated GraphQL code

GraphQL ensures agents can construct valid operations. It does not ensure they construct good ones.

Consider this query:

1{2  user(id: "123") {3    name4    email5  }6}

It works. It is anonymous, making it harder to identify in server logs and debugging tools, uses a hardcoded ID (not reusable), and omits the id field (preventing cache normalization in Apollo Client). An experienced developer would write:

1query GetUser($id: ID!) {2  user(id: $id) {3    id4    name5    email6  }7}

Named operation. Variables. Includes id for caching. These details compound across a codebase.

Apollo Skills encode this knowledge as reusable modules for AI coding tools. When an agent writes GraphQL, the graphql-operations skill guides it toward named queries, proper variables, and cache-friendly field selection. When an agent designs a schema, the graphql-schema skill enforces intentional nullability and proper list patterns ([Item!]! instead of [Item]).

Skills work with Claude Code, Cursor, GitHub Copilot, Windsurf, and other AI coding tools. Install with:

1npx skills add apollographql/skills

The CLI detects your tools and configures them automatically. Skills activate based on context, or you can invoke them directly (e.g., /graphql-schema in Claude Code).

When to adopt this layer: Your team uses AI coding tools. You want generated code to follow your conventions without re-explaining them every session. You have standards for schema design, operation structure, or Apollo product usage that you want agents to follow.

Layer 3: Apollo MCP Server as the capability layer for secure AI agent API execution 

Skills teach agents how to write good GraphQL. MCP Server gives them the ability to execute it.

Apollo MCP Server exposes GraphQL operations as MCP tools that agents can call. You control which operations are available through three configuration patterns:

Pre-defined operations: You write .graphql files. Each becomes an MCP tool with a typed input schema. Agents execute only what you have explicitly approved.

Persisted queries: If you use Apollo GraphOS, agents can execute operations from your persisted query manifest. Safelisting is automatic.

Dynamic introspection: Agents explore your schema and construct operations at runtime. Flexibility increases, but so does the need for security controls. Apollo Router’s demand control feature calculates operation cost and rejects expensive queries before execution.

Most teams combine patterns: pre-defined operations for mutations (explicit control over writes) and introspection for queries (flexibility 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

When to adopt this layer: You want agents to execute GraphQL operations, not just generate code. You need security boundaries around what agents can do. You want to control mutation access separately from query access.

How the layers work together

A typical workflow using all three layers:

1. Developer asks an AI coding tool to add a feature that fetches user order history
2. Skills layer: The graphql-operations skill activates, guiding the agent to use named queries, variables, and include id fields
3. MCP layer: The agent uses MCP Server’s search tool to find relevant types (User.orders, Order.status)
4. GraphQL layer: The agent constructs an operation and uses MCP Server’s validate tool to check it against the schema
5. MCP layer: The agent executes the validated operation through MCP Server’s execute tool
6. Skills layer: The agent writes client code following Apollo Client conventions from the apollo-client skill

Each layer contributes something the others cannot provide. GraphQL provides the typed contract. Skills provide knowledge. MCP Server provides the controlled execution.

Choosing your entry point

Not every team needs all three layers immediately. Start where your pain is sharpest.

If agents generate working but low-quality code: Start with Skills. Installation takes one command, requires no infrastructure changes, and improves every AI coding session immediately.

If agents make repeated invalid API requests: Start with GraphQL. The validation benefits apply whether you adopt Skills or MCP Server later.

If you need agents to execute operations in production: Start with MCP Server. Begin with pre-defined operations (Pattern 1) for explicit control, then expand to introspection if needed.

The layers compose incrementally. You can adopt Skills today, add MCP Server next quarter, and migrate to GraphQL over time. Each layer delivers value independently while enabling the next.

Next steps

To go deeper on any layer:

GraphQL: See Every Token Counts: Building Efficient AI Agents with GraphQL and Apollo MCP Server for detailed MCP Server configuration

Skills: See Apollo Skills: Teaching AI Agents How to Use Apollo and GraphQL for the full skill catalog and installation guide

MCP Server: Explore the Apollo MCP Server documentation for configuration reference

Apollo MCP Server and Apollo Skills are both open source. Try them in a single project before rolling out to your team.

Written by

Camille Lawrence

Read more by Camille Lawrence