Демо Apollo MCP

В этой папке настроена та же базовая архитектура, которую Apollo демонстрирует для MCP:

1. обычный GraphQL API,

2. Apollo MCP Server перед ним,

3. небольшой список разрешенных операций GraphQL, которые становятся инструментами MCP.

В этой версии используется автономный контейнер Apollo MCP Server вместо мастера rover init --mcp, так как его проще запустить локально без учетных данных GraphOS.

Что запускается

• api: небольшой Apollo Server на http://localhost:4001/

• mcp: Apollo MCP Server на http://localhost:8000/mcp

Related MCP server: mcp4gql

Схема архитектуры

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

Запуск

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

Во втором терминале проверьте MCP-сервер:

npx @modelcontextprotocol/inspector

Затем откройте URL инспектора, который он выведет, и выберите:

• Тип транспорта: Streamable HTTP

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

Нажмите Connect, затем List Tools.

Вы должны увидеть инструменты MCP, полученные из:

• GetBooks

• GetBookById

• GetBooksByGenre

Дополнительная конфигурация клиента

Для MCP-клиентов, использующих mcp-remote, локальная конфигурация выглядит так:

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

Что происходит на самом деле

GraphQL API по-прежнему является реальной службой данных. Он знает схему, разрешает поля и возвращает JSON для запросов GraphQL.

Apollo MCP Server не заменяет этот API. Он располагается перед ним и преобразует одобренные операции GraphQL в инструменты MCP, которые может обнаружить и вызвать ИИ-клиент.

Важные файлы:

• mcp-config.yaml: сообщает Apollo MCP Server, где находится конечная точка GraphQL, где находится файл схемы, где находятся разрешенные операции и как предоставлять MCP через HTTP.

• graphql/api.graphql: снимок схемы, используемый Apollo MCP Server, чтобы он мог правильно описывать инструменты.

• graphql/operations/GetBooks.graphql: один одобренный запрос, который становится одним инструментом MCP.

• src/server.mjs: фактическая реализация GraphQL API.

• docker-compose.yml: запускает обе службы вместе в одной локальной сети.

Поток запроса:

1. Ваш MCP-клиент подключается к http://localhost:8000/mcp.

2. Apollo MCP Server анонсирует инструменты на основе файлов операций .graphql.

3. Клиент вызывает один из этих инструментов с аргументами.

4. Apollo MCP Server преобразует этот вызов инструмента обратно в базовую операцию GraphQL.

5. Apollo MCP Server отправляет этот запрос GraphQL на http://api:4001/.

6. GraphQL API выполняет запрос и возвращает данные.

7. Apollo MCP Server возвращает результат MCP-клиенту в формате MCP.

Схема потока запросов

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

Почему здесь нет маршрутизатора (router)

Apollo Router полезен, когда:

• вы обслуживаете федеративный суперграф,

• вам нужна среда выполнения Apollo, управляемая GraphOS,

• или вы хотите, чтобы GraphQL и MCP были объединены в Apollo Runtime.

Для простого локального демо с одним существующим GraphQL API документация по развертыванию Apollo поддерживает использование автономного контейнера Apollo MCP Server непосредственно для этой конечной точки. Именно это и использует данный проект.

Источники

• Краткое руководство по Apollo MCP Server: https://www.apollographql.com/docs/apollo-mcp-server/quickstart

• Справочник по конфигурации Apollo MCP Server: https://www.apollographql.com/docs/apollo-mcp-server/command-reference

• Документация по развертыванию Apollo MCP Server: https://www.apollographql.com/docs/apollo-mcp-server/deploy

• Документация по отладке Apollo MCP Server: https://www.apollographql.com/docs/apollo-mcp-server/debugging