Apollo MCP 데모

이 폴더는 Apollo가 MCP를 위해 시연하는 핵심 아키텍처를 동일하게 설정합니다:

1. 일반적인 GraphQL API,

2. 그 앞에 위치한 Apollo MCP 서버,

3. MCP 도구가 되는 GraphQL 작업의 소규모 허용 목록.

이 버전은 GraphOS 자격 증명 없이 로컬에서 더 간단하게 실행할 수 있도록 rover init --mcp 마법사 대신 독립형 Apollo MCP 서버 컨테이너를 사용합니다.

시작되는 항목

• api: http://localhost:4001/에서 실행되는 작은 Apollo 서버

• mcp: http://localhost:8000/mcp에서 실행되는 Apollo 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

그런 다음 출력된 Inspector URL을 열고 다음을 선택합니다:

• Transport Type: Streamable HTTP

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

Connect를 클릭한 다음 List Tools를 클릭합니다.

다음에서 파생된 MCP 도구가 표시되어야 합니다:

• GetBooks

• GetBookById

• GetBooksByGenre

선택적 클라이언트 구성

mcp-remote를 사용하는 MCP 클라이언트의 경우 로컬 구성 형태는 다음과 같습니다:

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

실제로 일어나는 일

GraphQL API는 여전히 실제 데이터 서비스입니다. 스키마를 알고, 필드를 확인하며, GraphQL 쿼리에 대한 JSON을 반환합니다.

Apollo MCP 서버는 해당 API를 대체하지 않습니다. 그 앞에 위치하여 승인된 GraphQL 작업을 AI 클라이언트가 검색하고 호출할 수 있는 MCP 도구로 변환합니다.

중요한 파일은 다음과 같습니다:

• mcp-config.yaml: GraphQL 엔드포인트가 어디에 있는지, 스키마 파일이 어디에 있는지, 허용된 작업이 어디에 있는지, 그리고 MCP를 HTTP를 통해 노출하는 방법을 Apollo MCP 서버에 알려줍니다.

• graphql/api.graphql: Apollo MCP 서버가 도구를 올바르게 설명할 수 있도록 사용하는 스키마 스냅샷입니다.

• graphql/operations/GetBooks.graphql: 하나의 MCP 도구가 되는 승인된 쿼리 하나입니다.

• src/server.mjs: 실제 GraphQL API 구현입니다.

• docker-compose.yml: 두 서비스를 하나의 로컬 네트워크에서 함께 실행합니다.

요청 흐름은 다음과 같습니다:

1. MCP 클라이언트가 http://localhost:8000/mcp에 연결합니다.

2. Apollo MCP 서버가 .graphql 작업 파일을 기반으로 도구를 광고합니다.

3. 클라이언트가 인수를 사용하여 해당 도구 중 하나를 호출합니다.

4. Apollo MCP 서버가 해당 도구 호출을 기본 GraphQL 작업으로 다시 변환합니다.

5. Apollo MCP 서버가 해당 GraphQL 요청을 http://api:4001/로 보냅니다.

6. GraphQL API가 쿼리를 실행하고 데이터를 반환합니다.

7. Apollo MCP 서버가 결과를 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

여기에 라우터가 없는 이유

Apollo Router는 다음과 같은 경우에 유용합니다:

• 연합 슈퍼그래프(federated supergraph)를 제공하는 경우,

• Apollo의 GraphOS 관리 런타임을 원하는 경우,

• 또는 GraphQL과 MCP를 Apollo 런타임에 번들로 묶고 싶은 경우.

기존 GraphQL API 하나를 사용하는 간단한 로컬 데모의 경우, Apollo의 자체 배포 문서는 해당 엔드포인트에 대해 독립형 Apollo MCP 서버 컨테이너를 직접 사용하는 것을 지원합니다. 이 프로젝트가 사용하는 방식이 바로 이것입니다.

출처

• Apollo MCP 서버 퀵스타트: https://www.apollographql.com/docs/apollo-mcp-server/quickstart

• Apollo MCP 서버 구성 참조: https://www.apollographql.com/docs/apollo-mcp-server/command-reference

• Apollo MCP 서버 배포 문서: https://www.apollographql.com/docs/apollo-mcp-server/deploy

• Apollo MCP 서버 디버깅 문서: https://www.apollographql.com/docs/apollo-mcp-server/debugging