MCP 서버 만들기 — 트랜스포트, 스코프, 인증

도구를 애플리케이션 코드에 직접 연결하면, 그 도구의 형식(스키마)과 동작을 모두 그 앱 안에서 관리하게 됩니다. 같은 외부 서비스를 세 개의 앱이 써야 한다면, 앱마다 같은 연결을 따로 만들어 각자 유지해야 합니다. MCP(Model Context Protocol)는 이 도구 정의를 개별 앱에서 떼어 내, 하나의 서버라는 프로세스로 옮깁니다.

MCP 서버는 도구·리소스·프롬프트를 내놓는 프로세스이고, MCP 클라이언트가 여기에 연결해 그 기능을 씁니다. Claude Code에는 MCP 클라이언트가 들어 있어서, 서버에 연결하면 그 서버가 제공하는 도구를 찾아내고 작업 중에 불러 쓸 수 있습니다. 핵심은 기능을 한 번만 만들면, 거기에 연결하는 모든 클라이언트가 통합을 다시 구현하지 않고도 그 기능을 쓸 수 있다는 점입니다.

서버가 내놓는 것은 세 가지입니다. 도구는 앞에서 다룬, 모델이 호출해 실행하는 동작입니다. 나머지 둘은 도구 호출만으로는 얻기 어려운 경우를 위한 것입니다.

• 리소스(resource)는 서버가 내놓는 읽기 전용 데이터입니다. 모델이 도구를 호출해 가져오는 대신, 클라이언트가 주소로 요청하면 서버가 그 데이터를 돌려줍니다. 형태는 두 가지입니다 — 주소가 고정된 직접 리소스(예: 사용할 수 있는 문서 목록처럼 매개변수가 없는 데이터)와, 주소에 값을 넣는 템플릿 리소스(예: 문서 식별자를 받아 그 문서를 가리키는 주소). 턴을 시작할 때부터 특정 데이터가 맥락에 들어와 있어야 하고, 도구를 호출해 가져오는 것보다 곧바로 넣는 편이 더 싸고 예측 가능할 때 리소스를 씁니다. 다만 리소스 지원 여부는 클라이언트마다 다르므로, 쓰기 전에 내 클라이언트가 리소스를 맥락에 넣는 방법을 갖추고 있는지 확인해 볼 필요가 있습니다.
• 프롬프트(prompt)는 서버가 미리 만들어 둔 지시문 틀입니다. 사용자마다 직접 문장을 쓰게 하는 대신, 검증된 프롬프트를 이름으로 불러 쓰게 해 줍니다. 사용자가 웬만한 작업은 자기 말로도 시킬 수 있으니, 프롬프트는 정확한 문구가 중요할 때 쓸모가 있습니다. 잘 다듬은 지시문이 사용자가 즉석에서 입력하는 것보다 확실히 나은 결과를 내고, 그 품질을 모든 클라이언트가 똑같이 받게 하고 싶은 작업이 여기에 해당합니다. 지시문을 서버에 모아 두면 한곳에서 관리하면서 연결된 모든 곳에서 재사용하게 됩니다.

트랜스포트는 MCP 클라이언트와 서버가 신호를 주고받는 통신 방식입니다. 어떤 트랜스포트가 맞는지는 서버가 어디서 실행되는지에 따라 갈립니다. 세 가지가 있는데, 새로 만드는 서버라면 실제로는 앞의 둘 중에서 고르게 됩니다.

연결한 MCP 서버는 저마다 도구 정의를 딸려 오는데, 이것을 처음부터 다 불러오면 컨텍스트 창모델이 한 번의 요청에서 읽어 들이는 정보가 담기는 공간. 크기에 한계가 있다.을 차지합니다. Claude Code는 기본적으로 이 정의들을 미뤄 두었다가, 작업에 필요할 때 검색 단계로 관련 도구만 찾아 불러옵니다. 그래서 실제로 쓰이는 도구만 맥락에 들어옵니다.

정의를 처음부터 불러오는 방식도 선택할 수 있습니다. 이 경우 도구 정의가 컨텍스트 창의 대략 10% 안에 들어오면 미리 싣고, 그 한도를 넘으면 그때만 미룹니다. 어느 쪽이든, 필요한 서버만 연결해 두는 것이 요청을 가볍게 유지하는 방법입니다. 연결된 서버 하나하나가 모델이 고려해야 할 도구 목록을 늘리기 때문입니다.

같은 내용을 두 번 계산하지 않기 — 프롬프트 캐싱. 요청은 매번 입력을 처음부터 다시 처리하는데, 지난 요청과 똑같았던 부분까지 다시 처리합니다. 그만큼 비용이 되풀이됩니다. 프롬프트 캐싱은 잘 바뀌지 않는 앞부분을 저장해 두었다가 다음 요청에서 그대로 재사용해, 같은 부분을 두 번 계산하지 않게 해 줍니다.

캐싱은 요청 앞쪽의 안정된 구간을 처리한 결과를 저장합니다. 첫 요청이 이 구간을 캐시에 적어 두면, 이어지는 요청은 같은 지점까지 똑같은 내용을 훨씬 적은 비용으로 재사용합니다. 단, 내용이 정확히 일치해야 합니다 — 캐시 지점 앞에서 글자 하나만 바뀌어도 그 캐시는 무효가 되고 다시 적게 됩니다. 그래서 캐싱에 가장 잘 맞는 부분은 좀처럼 바뀌지 않는 구간입니다. 긴 시스템 프롬프트, 큰 도구 정의 묶음, 여러 질문을 던지는 참고 문서 같은 것들이 여기에 해당합니다.

캐싱은 캐시 지점(breakpoint)을 표시해야 켜집니다. 전체를 한 번에 켜는 설정은 없습니다. Messages API에서는 캐시하려는 마지막 블록에 ephemeral 타입의 cache_control 필드를 더합니다. 그러면 그 블록까지가 캐시됩니다. 지점은 최대 네 개까지 둘 수 있습니다. 요청은 도구 → 시스템 프롬프트 → 메시지의 정해진 순서로 처리되므로, 도구 다음에 지점을 두면 도구 정의는 캐시하면서 메시지는 그때그때 바뀌게 둘 수 있습니다.

캐시에는 시간 제한이 있습니다. 기본 수명은 마지막 읽기로부터 5분이고, 지점에 ttl을 1h로 지정하면 한 시간짜리 수명을 선택할 수 있습니다. 5분 기본값은 몇 분마다 요청이 오가는 방식에 맞습니다 — 읽을 때마다 시계가 다시 시작되기 때문입니다. 한 시간 옵션은 요청 사이 간격이 긴 작업, 예컨대 단계마다 잠시 멈추는 에이전트처럼 5분 창이 다음 요청 전에 끝나 버리는 경우에 맞습니다. 창이 다음 요청 전에 끝나면, 읽어서 얻는 이득 없이 적는 비용만 다시 치르게 됩니다. 한 가지 더 — 캐싱은 최소 토큰 기준(현재 대부분의 모델에서 1,024토큰)을 넘겨야 적용되므로, 짧은 프롬프트는 지점을 표시해도 캐시되지 않습니다.

컨텍스트 비용 문제는 참고 자료가 많을 때도 똑같이 생깁니다. 모델은 매 요청마다 컨텍스트 창에 든 것을 전부 읽으므로, 앞에 문서를 많이 실을수록 맥락은 그만큼 차고 정작 일할 공간은 줄어듭니다. 검색 증강 생성(RAG)은 이 문제를 푸는 방식입니다. 모든 문서를 맥락에 싣는 대신, 자료를 컨텍스트 창 밖에 저장해 두고, 지금 요청에 가장 관련 있는 부분만 찾아 그때그때 모델에 건넵니다. 모델은 자료 전체가 아니라 그 찾아낸 조각을 근거로 답을 만듭니다.

RAG는 두 가지 형태로 나뉩니다.

• 고전적 RAG(classical RAG)는 힘든 일을 미리 해 둡니다. 누가 질문하기 전에 원자료를 조각으로 나누고, 각 조각을 뜻을 수학적으로 담은 숫자 묶음(임베딩글 조각의 의미를 숫자들의 좌표로 바꾼 것. 뜻이 비슷할수록 좌표가 가깝다.)으로 바꿔 저장소에 담아 둡니다. 질문이 들어오면 그 질문도 같은 방식의 숫자로 바꾼 뒤, 숫자가 가장 비슷한 조각을 찾습니다. 도서관이 문을 열기 전에 사서가 모든 책을 읽고 장마다 정확한 요약 카드를 만들어 두는 것과 비슷합니다. 질문을 들고 가면 맞는 카드를 곧바로 꺼내 주는 셈입니다.
• 에이전트 검색(agentic search)은 미리 색인해 두는 과정을 아예 건너뜁니다. 준비된 저장소가 없습니다. 대신 모델이 질문을 받은 그 순간에 무엇이 필요한지 판단하고 직접 찾아 나섭니다 — 실시간으로 자료를 검색하고, 필요할 때 문서를 읽고, 일이 풀리는 대로 결과를 끌어옵니다. 미리 만든 카드를 뒤지는 대신, 질문을 받으면 직접 가서 답을 찾아오는 연구자에 가깝습니다.

이름은 몰랐어도 에이전트 검색을 이미 만난 적이 있을 수 있습니다. Claude Code에서 외부 도구(MCP 서버)를 여럿 연결하면, Claude는 모든 도구 정의를 처음부터 불러오지 않습니다 — 한꺼번에 들고 있기엔 너무 많기 때문입니다. 대신 지금 작업에 필요한 도구만 찾아 불러옵니다. Claude.ai의 프로젝트도 올려 둔 문서에 같은 방식으로 동작합니다. 지식 자료가 활성 창에 다 들어가지 못할 만큼 커지면, 전부 싣는 대신 질문마다 가장 관련 있는 문서 부분만 꺼내 옵니다.

두 방식이 하는 근본적인 일은 같습니다. 둘 다 자료에서 관련 있는 조각을 찾아 거기서 답을 만듭니다. 차이는 시점입니다. 고전적 RAG는 미리 만들어 둔 색인에 맞춰 조각을 찾고, 에이전트 검색은 필요한 순간에 검색해 찾습니다.

RAG를 쓰기 전에 알아 두면 좋은 성질이 두 가지 있습니다.

• 규모에 잘 견딥니다. 원자료가 늘어도 요청 하나의 비용은 대체로 그대로입니다. 모델은 언제나 그 질문에 관련된 조각만 받고 자료 전체를 받지 않기 때문입니다. 지식 자료가 문서 수천 건으로 커져도 질문 하나가 끌어오는 분량은 대략 비슷하게 유지됩니다.
• 찾아낸 만큼만 좋습니다. 모델은 받은 조각을 근거로 추론합니다. 검색 단계가 정작 필요한 문서를 놓치면 모델은 그 문서를 아예 보지 못합니다. 그래서 자료를 어떻게 정리해 두는지가 중요합니다. 이름이 모호한 파일(notes_final_v3.pdf)은 이름이 구체적인 파일(Q3 환불 정책, 2024년 8월 갱신)보다 찾아내기 어렵습니다. 관련 파일을 묶어 두는 것도 도움이 됩니다. 좋은 검색은 잘 정리된 원자료에서 시작합니다.

스코프는 어떤 사용자와 프로젝트가 이 서버를 불러올지를 정합니다. 스코프마다 설정을 저장하는 위치가 다릅니다. 네 가지가 있습니다.

서버를 연결하면 그 서버의 도구 목록 전체가 열립니다. 그런데 대개는 에이전트가 모든 도구를 확인 없이 쓰게 두고 싶지는 않습니다. 앞의 권한 모드 절에서 본 권한 층위는 MCP 도구에도 이어지고, 규칙이 서버 전체가 아니라 도구 하나를 지목할 수 있습니다.

권한 규칙에서 MCP 도구는 서버 이름과 도구 이름으로 표시합니다 — mcp__server__tool 형태입니다(서버 이름과 도구 이름을 이중 밑줄로 잇습니다). 예를 들어 mcp__github_create_issue에 허용 규칙을 걸면 그 도구 하나만 확인 없이 실행되고, GitHub 서버의 다른 도구들은 여전히 확인을 거칩니다. 쓰기 권한이 있는 도구에 거부 규칙을 걸면 그 도구는 막히고, 같은 서버의 읽기 전용 도구들은 그대로 쓸 수 있습니다. 넓은 서버를 연결해 두되 에이전트가 쓸 수 있는 범위는 좁게 유지하는 방법입니다. 도구 하나에 건 거부는 서버 전체에 건 허용을 이깁니다.

API MCP 커넥터를 쓸 때는 또 다른 방법이 있습니다. 커넥터로 서버에 연결하는 경우, mcp_toolset 객체에서 도구별로 enabled 플래그를 켜고 끌 수 있습니다. 이 플래그를 쓰면 서버를 등록하되 모델에게 보여 줄 도구만 노출할 수 있습니다. 권한 규칙은 노출된 도구를 실행해도 되는지를 정하고, enabled 플래그는 모델이 그 도구를 아예 보는지를 정합니다. 앞쪽은 통제(거버넌스) 장치, 뒤쪽은 컨텍스트 비용·범위 장치입니다. 둘은 함께 쓰는 경우가 많습니다. 다만 정확한 규칙 문법과 커넥터 베타 헤더는 발행 전에 공식 문서에서 확인해 보는 것이 좋습니다.

지금까지 본 트랜스포트·스코프·인증이 실제 서버에서 어떻게 맞물리는지, GitHub이 직접 관리하는 GitHub MCP 서버를 예로 살펴봅니다. 이 서버는 원격 서버로, 풀 리퀘스트 검토·이슈 열기·코드 검색 같은 저장소 관리 도구를 내놓습니다.

GitHub 서버는 GitHub이 원격으로 호스팅하므로 HTTP 트랜스포트를 씁니다. 서버 URL을 주어 등록하면 클라이언트가 네트워크로 연결합니다. 스코프는, 팀 전체가 같은 저장소 도구를 써야 하면 프로젝트 스코프를, 나만 쓰면 로컬 스코프를 고릅니다.

인증은 개인 접근 토큰Personal Access Token. 특정 서비스에 접근할 권한을 담은 개인용 인증 키.(Personal Access Token)으로 합니다. GitHub에서 토큰을 발급한 뒤, MCP 설정의 요청 헤더에 Bearer 토큰으로 실어 보냅니다. 이 토큰은 반드시 환경 변수로 넣고 설정 파일에서는 그 변수를 참조하게 해야 합니다. .mcp.json에 값을 직접 적어 올리면 안 됩니다 — 커밋된 파일에 직접 적힌 토큰은 저장소 이력에 들어가고, 나중에 파일을 덮어써도 이력에서는 지워지지 않기 때문입니다.

OAuth브라우저 로그인으로 사용자를 인증하고, 토큰 발급·보관을 서비스가 대신 처리해 주는 인증 방식.는 다른 인증 방식으로, 서비스가 브라우저 로그인 흐름으로 사용자를 직접 인증하는 서버가 씁니다. Linear가 이 방식을 쓰는 예입니다. Linear MCP 서버에 처음 연결하면 클라이언트가 Linear 로그인 페이지로 넘겨주고, 접근을 승인하면 토큰이 자동으로 발급·저장됩니다. 손으로 옮겨 적거나 관리하는 자격 증명이 없습니다. OAuth는 서비스의 권한 모델이 사용자 신원에 묶여 있는 통합에 맞는 방식입니다.

정리하면, GitHub MCP는 내가 발급해 보관하는 자격 증명을 쓰고, Linear MCP는 로그인 흐름이 자격 증명을 대신 처리합니다. 둘 다 원격 HTTP 서버이고 트랜스포트·스코프 논리도 같습니다. 다른 것은 인증 단계뿐입니다.

MCP SETUP REFERENCE — 배포 상황별 트랜스포트·스코프

COST · COMPLEXITY · RISK — 서버를 늘리기 전에 따져 볼 것

언제 MCP 서버가 맞고, 언제 다른 길이 나은가

프로덕션에 낼 준비가 다 된 것처럼 보이는 설정에서도, 인증을 나중에 정리하려고 미뤄 둔 한 걸음이 문제가 되는 경우가 있습니다. 서버는 잘 동작하고, 팀에 공유할 설정이 필요하고, 인증 방식 정리는 넘겨준 뒤에 해도 될 것처럼 느껴집니다. 그 지름길이, 임시로 적어 둔 API 키를 설정 파일이 커밋되는 순간 공유된 자격 증명 유출로 바꿔 놓습니다.

한 개발자가 서비스 계정 API 키로 데이터 웨어하우스(대용량 데이터 저장소) MCP 서버에 연결했습니다. 설정 중에 서버를 빨리 띄우려고 키를 .mcp.json 설정 파일에 직접 적었습니다. 팀에 공유하기 전에 환경 변수로 옮길 생각이었습니다. 그런데 팀원들이 저장소를 내려받아 같은 서버에 연결할 수 있도록 .mcp.json을 프로젝트 저장소에 커밋했고, 키도 함께 올라갔습니다. 48시간 안에 팀원 셋이 저장소를 내려받았고, CI지속적 통합(Continuous Integration). 코드가 올라올 때마다 자동으로 내려받아 빌드·검사하는 시스템. 파이프라인도 새로 한 번 내려받았습니다. 이제 키는 네 곳에 있게 됐습니다 — 본인 기계, 저장소 이력, 팀원 세 대의 기계, 그리고 CI 실행 환경의 파일 시스템.

뒤늦게 알아차린 개발자는 키를 환경 변수로 옮기고 .mcp.json을 고쳐 다시 커밋했습니다. 하지만 키는 여전히 커밋 이력에 남아 있었고, 결국 서비스 계정을 교체해야 했습니다. 교체하자 같은 키로 설정돼 있던 외부 서비스 두 개가 멈췄고, 이를 고치는 데 세 시간이 들었습니다.

BEFORE — 쓰면 안 되는 방식 (설정 파일에 직접 적은 자격 증명)

{
  "type": "http",
  "url": "https://warehouse.internal/mcp",
  "headers": {
    "Authorization": "Bearer sk-abc123..."   ← 설정 파일에 직접 적은 자격 증명
  }
}

AFTER — 올바른 방식 (환경 변수 참조)

{
  "type": "http",
  "url": "https://warehouse.internal/mcp",
  "headers": {
    "Authorization": "Bearer ${WAREHOUSE_MCP_TOKEN}"   ← 환경 변수 참조
  }
}

원문의 점검 과제입니다. 아래 네 가지 배포 상황마다 알맞은 트랜스포트와 스코프를 골라 보세요. 정답을 먼저 떠올려 본 뒤 고르면 좋습니다. 맞히면 설명이 나옵니다.