MCP – AI에 도구를 연결하는 표준

MCP(Model Context Protocol)는 AI 애플리케이션을 외부 시스템에 연결하는 오픈소스 표준입니다. 공식 문서의 정의가 그렇고, 여기서 외부 시스템은 파일이나 데이터베이스 같은 데이터, 검색 엔진 같은 도구, 특화된 프롬프트 같은 작업 흐름을 가리킵니다.

앞에서는 MCP가 어떤 구성으로 되어 있고 서버가 무엇을 내주는지 공식 문서를 따라 정리합니다. 뒤에서는 제가 앱인토스 콘솔을 MCP로 연결해 쓰는 설정과 규칙을 원본 파일 그대로 보여 드릴게요.

MCP는 무엇을 정해 둔 규격인가

Anthropic의 공개 발표 글은 배경을 이렇게 적었습니다. 모델의 성능은 빠르게 좋아졌는데 정작 데이터와는 떨어져 있고, 데이터 소스가 하나 늘 때마다 연결을 따로 구현해야 해서 규모를 키우기 어렵다는 것입니다. MCP는 소스마다 따로 만들던 연결을 프로토콜 하나로 바꾸자는 제안이에요.

정해 둔 범위는 좁은 편이에요. 아키텍처 문서에 따르면 MCP는 컨텍스트를 주고받는 프로토콜만 다루고, AI 애플리케이션이 모델을 어떻게 쓰는지나 받은 컨텍스트를 어떻게 관리하는지는 정하지 않습니다.

호스트, 클라이언트, 서버로 나뉜다

MCP는 클라이언트-서버 구조를 따르고, 여기에 호스트, 클라이언트, 서버가 등장합니다.

호스트는 서버 하나마다 클라이언트를 하나씩 만들고, 클라이언트는 자기 서버와 전용 연결을 유지합니다. 서버를 셋 연결하면 호스트 안에 클라이언트가 셋 생기는 식이에요.

서버가 내주는 도구, 리소스, 프롬프트

서버가 클라이언트에 내놓을 수 있는 것을 공식 문서는 프리미티브라고 부르고, 핵심으로 다음을 듭니다.

• 도구(Tools): AI 애플리케이션이 호출해서 동작을 수행하는 실행 가능한 함수. 파일 작업, API 호출, 데이터베이스 질의가 예로 나옵니다.
• 리소스(Resources): 컨텍스트가 되는 데이터. 파일 내용, 데이터베이스 레코드 같은 것입니다.
• 프롬프트(Prompts): 모델과의 상호작용을 짜 주는 재사용 템플릿.

문서의 예시로 보면 차이가 분명해집니다. 데이터베이스를 다루는 MCP 서버라면 질의를 실행하는 도구, 스키마를 담은 리소스, 도구 사용 예시가 들어 있는 프롬프트를 각각 내줄 수 있어요.

도구가 호출되는 과정은 아래 그림과 같습니다. 클라이언트가 tools/list로 서버의 도구 목록을 받고, 대화 중에 모델이 도구를 쓰기로 하면 AI 애플리케이션이 그 호출을 해당 서버로 보내 tools/call로 실행한 뒤 결과를 대화에 돌려줍니다.

연결 방식은 두 가지다

메시지 형식은 JSON-RPC 2.0이고, 그 메시지를 실어 나르는 방식이 둘 있어요.

어느 방식을 쓰든 메시지 형식은 같고요. 문서에 따르면 로컬 서버는 보통 클라이언트 하나를 상대하고, 원격 서버는 보통 여러 클라이언트를 상대합니다.

공개 발표와 초기 도입 사례

MCP는 Anthropic이 2024년 11월 25일에 오픈소스로 공개했습니다. 발표 글에 따르면 Anthropic에서 David Soria Parra와 Justin Spahr-Summers가 만들었어요. 공개 당시 내놓은 것은 규격과 SDK, Claude 데스크톱 앱의 로컬 MCP 서버 지원, 서버 오픈소스 저장소였습니다. Google Drive, Slack, GitHub, Git, Postgres, Puppeteer용 서버도 미리 만들어 함께 공개했고요.

같은 글에 이름이 나오는 초기 도입 사례는 Block과 Apollo입니다. 두 곳은 MCP를 자기 시스템에 통합했다고 소개됐고, 개발 도구 회사인 Zed, Replit, Codeium, Sourcegraph는 자기 플랫폼에 MCP를 적용하는 작업을 하고 있다고 적혀 있습니다.

MCP 소개 문서는 Claude와 ChatGPT 같은 AI 어시스턴트, Visual Studio Code와 Cursor 같은 개발 도구가 MCP를 지원한다고 적고 있어요. 한 번 만들어 여러 곳에 붙일 수 있다는 점을 문서는 이점으로 듭니다.

앱인토스 콘솔을 MCP 서버로 연결했다

여기부터는 제 프로젝트 이야기입니다. 앱인토스 콘솔은 미니앱을 등록하고 번들을 올리고 검수를 요청하는 곳인데, 이 콘솔 작업을 MCP 서버로 연결해 두었어요.

설정은 프로젝트 폴더의 .mcp.json 한 파일입니다. 주소와 클라이언트 ID 값만 가렸어요.

{
  "mcpServers": {
    "apps-in-toss-console": {
      "type": "http",
      "url": "(가림)",
      "oauth": {
        "clientId": "(가림)"
      }
    }
  }
}

type은 http로, 앞에서 본 두 방식 가운데 HTTP 쪽입니다. 인증 항목은 oauth로 적혀 있고요. Claude Code 문서는 MCP 서버를 등록하는 범위를 로컬, 프로젝트, 사용자로 나누는데, 프로젝트 루트의 .mcp.json에 적는 것이 프로젝트 범위예요. Claude Code 문서에 따르면 이 범위의 서버는 대화형 세션에서 쓰기 전에 승인을 묻습니다.

같은 문서의 범위 표를 옮기면 이렇습니다.

콘솔 MCP가 제공하는 도구

콘솔 MCP의 도구 목록은 문서 하나로 받아 뒀는데, 그 문서 기준으로 도구는 102개입니다. 이름 앞머리를 따라 제 나름대로 묶어 보면 이렇습니다. 자주 쓰는 묶음만 골랐어요.

이 밖에 인앱구매, 프로모션, 워크스페이스, 공지사항, 이벤트, 토스 로그인 등의 도구가 있습니다.

읽어 보면 도구 설명이 꽤 깁니다. 검수 요청 도구인 bundle_submit_review의 설명에는 그 전에 테스트 푸시가 성공해 있어야 한다는 사전 조건이 적혀 있고, 약관 동의가 필요한 도구에는 동의는 MCP로 할 수 없으니 재시도하지 말고 콘솔 웹에서 처리하라고 적혀 있어요. 앞에서 본 tools/list 응답의 설명 칸이 실제로 어떻게 채워지는지 보여 주는 예입니다.

AI 하네스 글에서 소개한 스크립트도 이 묶음을 그대로 씁니다. 앱의 준비 상태를 점검하는 명령이 출력 끝에 MCP 작업 순서를 붙여 주거든요.

    mcpFlow: [
      'miniapp_create / miniapp_update_*: console identity and category',
      'bundle_* + review_*: upload, test, and review',
      'iaa_* + dashboard_*: ad and retention measurement',
      'push_template_*: functional notification consent/template',
      'console-only: final release and advertising smart-message campaign execution',
    ],

마지막 줄에는 최종 출시와 광고성 스마트 메시지 캠페인 집행을 콘솔에서만 하는 일로 따로 적어 뒀어요.

연결됐는지 확인하고, 안 되면 추측하지 않는다

설정 파일에 서버가 적혀 있다고 해서 지금 세션에서 도구를 부를 수 있는 건 아닙니다. Claude Code의 claude mcp list는 서버마다 연결됨, 인증 필요, 연결 실패 같은 상태를 옆에 보여 주는데, 하네스 스크립트의 mcp 명령이 이 출력을 이용합니다. 아래는 그 분기 하나를 떼어 온 것이에요.

} else if (command === 'mcp') {
  let found = false;
  for (const [agent, args] of [['codex', ['mcp', 'list']], ['claude', ['mcp', 'list']]]) {
    const result = spawnSync(agent, args, { cwd: root, encoding: 'utf8' });
    if (result.error) {
      console.log(`${agent}: not available (${result.error.code ?? result.error.message})`);
      continue;
    }
    const line = `${result.stdout}\n${result.stderr}`.split('\n').find((item) => item.includes(config.consoleMcp));
    console.log(line ? `${agent}: ${line.trim()}` : `${agent}: ${config.consoleMcp} not configured`);
    if (line) found = true;
  }
  if (!found) console.log('Configuration is missing. Registered configuration alone does not expose tools; use MCP only when its tools are callable in this session.');

Codex와 Claude Code 양쪽에 mcp list를 실행하고, 출력에서 콘솔 서버 이름이 들어 있는 줄을 찾아 그대로 보여 줍니다. 스크립트는 서버 이름을 하네스 설정 파일에서 읽어 와요. 어느 쪽에서도 못 찾으면 설정이 없다는 안내를 덧붙입니다.

문서에 적힌 상태 표기와 이 명령이 찍는 형식을 한 장에 옮기면 아래와 같습니다. 실행 결과를 찍은 것은 아니고 문서와 코드에 적힌 문자열을 옮긴 것이에요.

규칙 파일에는 그다음 행동까지 적어 뒀습니다.

- Console MCP server name: `apps-in-toss-console` (project scope, `.mcp.json`, OAuth). Check with
  `node scripts/ait-harness.mjs mcp`; if its tools are not callable in this session, finish the local
  work and report the exact console-only action instead of guessing.

추측하지 말라는 내용이고, 스킬 문서에도 MCP를 쓸 수 없으면 수동 작업을 보고하라는 규칙이 있어요. 순서로 풀면 이렇습니다.

글에 나온 규칙 파일과 에이전트는 Claude Code에서 쓰는 방식이고, 공식 안내는 Claude Code 공식 문서에 있습니다.

이 글은 직접 만들고 운영하며 남긴 기록입니다. 적힌 수치는 작성 시점의 제 계정 기준이며, 같은 결과나 수익을 보장하지 않습니다.