productmusings written by Jiri De Jagere

REST or GraphQL: Two Roads to Smarter AI Integrations


Updated:
4 minutes

REST or GraphQL: Two Roads to Smarter AI Integrations

There’s a quiet but important shift happening in how we expose APIs to AI agents. It’s no longer just about humans calling endpoints — it’s about models reasoning over them. That means the way we shape our APIs starts to matter again.

Lately I’ve been experimenting with two ways to expose structured operations to agents through the Model Context Protocol (MCP) — a standard that lets models use APIs as “tools.” Here’s what I’ve learned.

There are two ways to get your AI Agents to interact with backend systems via MCP tools:

  • REST + MCP: Each REST operation becomes its own MCP tool. Think: get_user, update_user, list_orders. Each tool has a clear name, parameters, and examples.
  • GraphQL + MCP: The REST layer stays behind the scenes. The agent interacts with a single GraphQL endpoint instead, writing its own queries and mutations.

GraphQL looks elegant — one endpoint, flexible schema, composable data. But AI agents are not frontend apps. Their strengths (and blind spots) are different.

REST is for reasoning, GraphQL is for expression

With REST + MCP, agents reason more easily. Each tool has a single purpose. Planning is simple: pick a tool, fill parameters, execute.

With GraphQL + MCP, agents express themselves more freely. One query can fetch multiple related entities at once, but the model has to construct valid query syntax and understand nested fields.

For example, fetching a user and their orders:

REST + MCP (two separate calls):

http
GET /users/123
GET /orders?userId=123

GraphQL + MCP (single query):

graphql
query GetUserWithOrders {
  user(id: "123") {
    id
    name
    email
    orders {
      id
      product
      status
      total
    }
  }
}

Making GraphQL LLM-friendly

GraphQL can be powerful but challenging for agents out of the box. Adding these enhancements makes it much easier:

  • Schema summaries: plain-language descriptions for each type and field.
  • Example queries: templates showing how to request data.
  • Semantic aliases: group related queries meaningfully (“user”, “order”).
  • Error hints: return human-readable errors for invalid queries.
  • Query validation: catch syntax issues before execution.

With these, agents can introspect, learn, and reuse good patterns instead of guessing syntax.

Comparing the approaches

REST + MCP

  • High discoverability: each tool is explicit.
  • Clear schema: parameters and results are straightforward.
  • Simple planning: pick a tool, fill in parameters.
  • Limited expressiveness: multiple calls needed for complex data.
  • High reliability: fewer syntax errors.
  • Moderate extensibility: adding new endpoints requires new tools.

GraphQL + MCP (with LLM enhancements)

  • Moderate discoverability: single endpoint, but schema summaries help.
  • Transparent schema: types and fields documented.
  • Planning complexity: requires query composition.
  • Excellent expressiveness: nested, composable data.
  • Robustness: improved with query templates and validation.
  • High adaptability: adding fields or types is backward compatible.

The hybrid sweet spot

In practice, a hybrid approach works best:

  • Reads / Queries → GraphQL + MCP Flexible and composable data retrieval.
  • Writes / Actions → REST + MCP Safer and more predictable for actions with side effects.

Example workflow: fetch a user and their orders, then update one order’s status.

Step 1 — Read (GraphQL + MCP):

graphql
query GetUserOrders {
  user(id: "123") {
    id
    name
    orders {
      id
      product
      status
    }
  }
}

Step 2 — Write (REST + MCP):

http
POST /orders/o2/status
{
  "status": "SHIPPED"
}

Agents can reason clearly about actions while retaining the flexibility to explore complex data.

Closing thought

APIs aren’t just for developers anymore. They’re interfaces for reasoning systems. That changes the design lens — from ergonomics for humans to semantics for models. These architectural decisions become part of building AI capabilities, not just features — reusable systems that help your organization learn and differentiate faster over time.

  • REST + MCP gives structure for reasoning.
  • GraphQL + MCP gives freedom for expression.

Pick the approach that fits your agent’s job — or blend both if you can.

  • REST + MCP when the agent should know what to do.
  • GraphQL + MCP when the agent should decide what to ask for.

  ai   ai agents   MCP   REST   GraphQL