MCP vs API: 주문 서비스 하나, 인터페이스 둘

"MCP vs API: REST가 이미 작동하는데 MCP가 왜 필요할까?" 영상의 동반 저장소입니다.

클론하고, 명령어 두 개 실행하고, 같은 작업을 두 번 해보세요. 한 번은 일반 REST API로, 한 번은 그 위에 MCP 서버를 얹어서요. 약 20분 정도 걸립니다.

무엇을 만드는가

작은 온라인 스토어를 운영한다고 가정합니다. 주문이 들어오고, 일부는 멈춰서 배송되지 않습니다. AI 에이전트가 멈춘 주문을 찾아 각각에 대해 GitHub 이슈를 열도록 하려고 합니다.

이게 전부입니다. 작고 실제적인 작업 하나.

첫 번째 방식은 에이전트에게 API 문서를 주고 curl을 쓰게 하는 것입니다. 에이전트는 어떤 엔드포인트를 호출할지 파악하고, "7일 이상"에 대한 날짜 필터를 만들고, 응답이 페이지로 나뉘어 온다는 것을 알아차리고, 센트를 달러로 변환해야 합니다.

두 번째 방식은 { older_than_days: 7 }을 받는 find_stale_orders라는 도구를 주는 것입니다.

둘 다 같은 엔드포인트 GET /orders를 호출합니다. 스토어는 전혀 바뀌지 않습니다. 바뀌는 것은 누가 생각을 하느냐입니다: 에이전트인지, 아니면 여러분의 서버인지.

                        ┌──────────────────────────────────┐
  Web frontend  ───────▶│                                  │
  Mobile app    ───────▶│   Orders service (Express)       │
  Microservice  ───────▶│   GET  /orders                   │
                        │   GET  /orders/:id               │
                        │   PATCH /orders/:id              │
                        └──────────────▲───────────────────┘
                                       │  plain HTTP, nothing AI specific
                        ┌──────────────┴───────────────────┐
  Claude Code   ───────▶│   Orders MCP server              │
  Cursor        ───────▶│   tool: find_stale_orders        │
  Codex         ───────▶│   input: { older_than_days: 7 }  │
                        └──────────────────────────────────┘

여러분의 API는 문입니다. MCP는 AI 클라이언트가 그 문을 열 수 있는 표준 손잡이를 제공합니다.

주문 서비스는 Claude Code가 존재한다는 사실을 전혀 모릅니다. MCP 서버는 여러분 API의 또 다른 HTTP 클라이언트일 뿐입니다. 유일한 차이는 에이전트가 이해하는 방식으로 자신을 설명한다는 점입니다.

Related MCP server: OHMS

1분 만에 시도해보기

Node 20 이상이 필요합니다. 그 외에는 아무것도 필요 없습니다. 데이터베이스도, API 키도 없습니다.

git clone https://github.com/bytemonk-academy/mcp-vs-api.git
cd mcp-vs-api
npm install
npm test

npm test는 REST API와 MCP 서버 양쪽에 대해 31개의 테스트를 실행합니다. 통과하면 모든 것이 작동하는 것이고, 나머지는 여러분이 지켜보기만 하면 됩니다.

이제 서비스를 시작하고 계속 실행해 둡니다:

npm run api

두 번째 터미널에서 데이터를 확인합니다:

npm run orders

  ID         CUSTOMER             STATUS      PLACED       DAYS  TOTAL
  ----------------------------------------------------------------------
  ORD-1001   Ada Lovelace         UNSHIPPED   2026-07-27   31    $129.00
  ORD-1002   Grace Hopper         UNSHIPPED   2026-08-03   24    $45.99
  ...

  Showing 20 of 24 matching orders.

  !! There are more. page.nextOffset = 20
     You have NOT seen all 24 orders.

그런 다음 이 데모의 핵심 질문을 던져보세요:

npm run orders -- --stale=7

주문 8건. 어떤 머신에서, 하루 중 어떤 시간에 실행해도 같은 8건입니다.

npm run orders는 무엇인가요?

curl의 단축어입니다.

여러분의 API에 GET /orders를 보내고 응답을 원시 JSON 대신 표로 출력합니다. 그게 전부입니다. 같은 요청을 직접 실행할 수도 있습니다:

curl "http://localhost:3000/orders"

같은 데이터를 얻지만 읽기는 더 어렵습니다. 이 스크립트는 데이터를 빠르게 확인하기 위한 것일 뿐입니다. 수업의 일부가 아닙니다. 1단계에서 에이전트는 curl과 문서만 받습니다. 그 외에는 아무것도 없습니다.

몇 가지 옵션을 받습니다:

npm run orders -- --stale=7             # unshipped for more than 7 days
npm run orders -- --status=UNSHIPPED    # filter by status
npm run orders -- --limit=5 --offset=5  # move through the pages by hand

테스트 데이터가 그렇게 생긴 이유

24개의 주문이 메모리에 저장되어 있고, 날짜는 오늘 기준으로 설정됩니다. 따라서 이 저장소를 클론하면 언제나 정확히 8개의 오래된 주문이 있습니다.

세 가지 문제가 의도적으로 심어져 있습니다. 영상의 말을 믿는 대신 직접 차이를 확인할 수 있도록요:

• 응답이 페이지로 나뉘어 옵니다. 주문을 요청하면 24개 중 20개를 받습니다. 그 20개 행에는 불완전해 보이는 것이 없습니다. 첫 페이지에서 멈추는 에이전트는 틀린 답을 확신에 차서 말합니다.

• 일부 오래된 주문은 취소되었습니다. 오래된 것처럼 보이지만 실제로는 아닙니다. status 대신 shippedAt으로 필터링하면 실수로 그들을 집계하게 됩니다.

• 일부 주문은 7일 기준선 바로 아래에 있습니다. 날짜 계산을 조금만 틀려도 오류 메시지가 아니라 틀린 합계가 나옵니다.

MCP 서버는 이 세 가지를 코드에서 한 번에 처리합니다. src/mcp/server.ts에서요. curl 버전에서는 에이전트가 매번 세 가지를 모두 올바르게 처리해야 합니다.

실습

순서대로 진행하세요. 1단계를 2단계보다 먼저 하는 것이 핵심입니다. 그 차이가 바로 교훈이기 때문입니다.

여기에도 있습니다: API 레퍼런스(1단계에서 에이전트에게 주는 문서), 복사해서 쓸 수 있는 프롬프트, 문제 해결.

2단계는 실제 GitHub 이슈를 열므로, 채워져도 괜찮은 테스트 저장소를 사용하세요.

여기 무엇이 들어있나

src/
  data/orders.ts     The 24 test orders
  api/app.ts         The REST API. Knows nothing about MCP.
  api/server.ts      Starts it on a port.
  mcp/server.ts      The MCP server. Calls the REST API over HTTP.
scripts/orders.ts    The table viewer used above
clients/             Plain MCP clients, in Python and TypeScript
tests/               Tests for both halves
docs/                The walkthrough
.mcp.json            Claude Code reads this automatically
.cursor/mcp.json     Cursor reads this automatically

도구 세 개. 각각은 이미 있는 엔드포인트를 얇게 감싼 것입니다:

src/mcp/server.ts는 약 170줄이고 대부분 주석입니다. MCP 서버라는 것이 사실 이게 전부입니다.

프로토콜을 직접 확인하기

Claude Code는 여기서 특별한 일을 하지 않습니다. 서버를 하위 프로세스로 시작하고 stdin과 stdout을 통해 JSON-RPC 메시지를 주고받을 뿐입니다. clients/raw_mcp_client.py는 같은 일을 수동으로 합니다:

async with stdio_client(server) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("find_stale_orders", {"older_than_days": 7})

같은 스크립트가 이어서 GitHub의 MCP 서버와 HTTP로 통신하여 이슈를 엽니다:

await session.call_tool("create_issue", {"owner": owner, "repo": name, "title": ...})

두 경우 모두 같은 형태입니다. 하나의 서버는 여러분 노트북의 Node 프로세스이고, 다른 하나는 GitHub이 운영합니다. 클라이언트는 둘을 구분할 수 없습니다. 그 점이 기억할 가치가 있는 부분입니다. 한 언어로 통일하고 싶다면 clients/에 TypeScript 버전도 있습니다.

테스트

npm test

31개의 테스트. MCP 테스트는 Claude Code와 같은 방식으로 stdio를 통해 실제 MCP 클라이언트를 구동합니다.

자체 서버를 작성할 계획이라면 읽어볼 가치가 있습니다. 실제로 확인할 가치가 있는 것들을 보여줍니다: 모든 도구에 사용 가능한 설명과 스키마가 있는지, 페이지네이션이 실제로 작동하는지, 404가 크래시 대신 도구 오류로 반환되는지, 취소된 주문이 결과에서 제외되는지.

명령어

npm run api        # REST API on :3000
npm run api:dev    # same, restarts when you edit a file
npm run orders     # print the orders as a table
npm run mcp        # run the MCP server directly (agents usually do this for you)
npm test           # the tests
npm run typecheck  # tsc --noEmit
npm run inspect    # MCP Inspector, to try the tools by hand

npm run inspect는 에이전트가 보는 것을 정확히 확인하는 가장 빠른 방법입니다: 도구 이름, 설명, 각 도구의 입력 스키마.

데이터는 메모리에 보관되므로 npm run api를 다시 시작하면 모든 것이 처음 상태로 돌아갑니다.

MCP는 언제 가치가 있나요?

1단계는 작동합니다. 속임수가 아닙니다. 좋은 에이전트는 curl과 문서만으로 오래된 주문을 찾아 이슈를 열 것입니다. MCP가 그 작업을 가능하게 만드는 것은 아닙니다.

MCP가 바꾸는 것은 통합의 형태입니다. 주문 서비스를 조회하는 방법이 이제 모든 에이전트의 컨텍스트 창 대신 하나의 서버에 있습니다. 같은 기능이 각각에 새 통합을 작성하지 않고도 Claude Code, Cursor, Codex에서 작동합니다. 그리고 어떤 기능을 노출할지 선택할 수 있는데, 이는 API 키를 넘겨주는 것과는 매우 다릅니다.

바꾸지 않는 것: 인증, 권한 부여, 검증, 속도 제한, 재시도, 그리고 좋은 서비스 설계는 여전히 여러분의 몫입니다. 설계가 나쁜 API 위에 MCP 서버를 얹어도 여전히 설계가 나쁜 API입니다.

대략적으로 가치는 클라이언트 수 곱하기 도구 수에 비례해 커집니다. 여러분이 제어하는 함수 두 개를 호출하는 에이전트 하나? 건너뛰세요. 그냥 함수를 호출하면 됩니다. 다섯 팀과 네 클라이언트에 걸친 도구 서른 개? 그때가 공유 프로토콜이 비용을 정당화하기 시작하는 시점입니다. docs/architecture.md에서 그 기준선이 어디인지 다룹니다.

MIT 라이선스. 여러분의 교육 자료에 출처 표시 없이 사용해도 됩니다.