Demo de Apollo MCP

Esta carpeta configura la misma arquitectura central que Apollo demuestra para MCP:

1. una API de GraphQL normal,

2. un servidor Apollo MCP delante de ella,

3. una pequeña lista de permitidos de operaciones GraphQL que se convierten en herramientas MCP.

Esta versión utiliza el contenedor independiente del servidor Apollo MCP en lugar del asistente rover init --mcp porque es más sencillo de ejecutar localmente sin credenciales de GraphOS.

Qué se inicia

• api: un pequeño servidor Apollo en http://localhost:4001/

• mcp: servidor Apollo MCP en http://localhost:8000/mcp

Related MCP server: mcp4gql

Diagrama de arquitectura

flowchart LR
    subgraph LocalMachine["Local machine"]
        Client["MCP client\nInspector / Codex / Cursor"]

        subgraph Docker["docker compose"]
            MCP["Apollo MCP Server\n:8000/mcp"]
            API["Apollo GraphQL API\n:4001"]
        end

        Ops["graphql/operations/*.graphql\nApproved operations"]
        Schema["graphql/api.graphql\nSchema snapshot"]
    end

    Client -->|"MCP over Streamable HTTP"| MCP
    Ops -->|"tool definitions"| MCP
    Schema -->|"schema metadata"| MCP
    MCP -->|"GraphQL queries/mutations"| API
    API -->|"GraphQL JSON response"| MCP
    MCP -->|"MCP tool results"| Client

Ejecución

cd C:\Users\muham\Documents\apollo-mcp
npm install
docker compose up --build

En una segunda terminal, inspecciona el servidor MCP:

npx @modelcontextprotocol/inspector

Luego abre la URL del inspector que aparece, elige:

• Tipo de transporte: Streamable HTTP

• URL: http://127.0.0.1:8000/mcp

Haz clic en Connect y luego en List Tools.

Deberías ver herramientas MCP derivadas de:

• GetBooks

• GetBookById

• GetBooksByGenre

Configuración opcional del cliente

Para clientes MCP que utilizan mcp-remote, la forma de la configuración local es:

{
  "mcpServers": {
    "apollo-demo": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}

Qué está ocurriendo realmente

La API de GraphQL sigue siendo el servicio de datos real. Conoce el esquema, resuelve los campos y devuelve JSON para las consultas GraphQL.

El servidor Apollo MCP no reemplaza esa API. Se sitúa delante de ella y traduce las operaciones GraphQL aprobadas en herramientas MCP que un cliente de IA puede descubrir y llamar.

Los archivos importantes son:

• mcp-config.yaml: indica al servidor Apollo MCP dónde reside el endpoint de GraphQL, dónde está el archivo de esquema, dónde residen las operaciones permitidas y cómo exponer MCP a través de HTTP.

• graphql/api.graphql: instantánea del esquema utilizada por el servidor Apollo MCP para que pueda describir las herramientas correctamente.

• graphql/operations/GetBooks.graphql: una consulta aprobada que se convierte en una herramienta MCP.

• src/server.mjs: la implementación real de la API de GraphQL.

• docker-compose.yml: ejecuta ambos servicios juntos en una red local.

El flujo de solicitud es:

1. Tu cliente MCP se conecta a http://localhost:8000/mcp.

2. El servidor Apollo MCP anuncia herramientas basadas en los archivos de operación .graphql.

3. El cliente llama a una de esas herramientas con argumentos.

4. El servidor Apollo MCP convierte esa llamada de herramienta de nuevo en la operación GraphQL subyacente.

5. El servidor Apollo MCP envía esa solicitud GraphQL a http://api:4001/.

6. La API de GraphQL ejecuta la consulta y devuelve los datos.

7. El servidor Apollo MCP devuelve el resultado al cliente MCP en formato MCP.

Diagrama de flujo de solicitud

sequenceDiagram
    autonumber
    participant C as MCP Client
    participant M as Apollo MCP Server
    participant O as Operation Files
    participant G as GraphQL API

    C->>M: Connect to http://localhost:8000/mcp
    M->>O: Load approved .graphql operations
    O-->>M: GetBooks / GetBookById / GetBooksByGenre
    M-->>C: Advertise MCP tools
    C->>M: Invoke tool with arguments
    M->>M: Convert tool call to GraphQL operation
    M->>G: Send GraphQL request to http://api:4001/
    G-->>M: Return GraphQL JSON data
    M-->>C: Return MCP-formatted tool result

Por qué no hay un router aquí

Apollo Router es útil cuando:

• estás sirviendo un supergrafo federado,

• quieres el tiempo de ejecución gestionado por GraphOS de Apollo,

• o quieres GraphQL y MCP integrados en Apollo Runtime.

Para una demo local sencilla con una API de GraphQL existente, los documentos de despliegue de Apollo admiten el uso directo del contenedor independiente del servidor Apollo MCP contra ese endpoint. Eso es lo que utiliza este proyecto.

Fuentes

• Inicio rápido del servidor Apollo MCP: https://www.apollographql.com/docs/apollo-mcp-server/quickstart

• Referencia de configuración del servidor Apollo MCP: https://www.apollographql.com/docs/apollo-mcp-server/command-reference

• Documentos de despliegue del servidor Apollo MCP: https://www.apollographql.com/docs/apollo-mcp-server/deploy

• Documentos de depuración del servidor Apollo MCP: https://www.apollographql.com/docs/apollo-mcp-server/debugging