MCP로 AI 코딩 에이전트를 내 도구와 연결하는 방법

AI 코딩 에이전트를 사용해 봤다면 아마 이런 벽에 부딪힌 적이 있을 것이다. 에이전트가 "데이터베이스를 볼 수 없습니다" 라거나 "이슈 상세 내용을 여기에 붙여넣어 주세요" 라고 말하는 순간 말이다. 에이전트는 똑똑하지만 갇혀 있다 — 파일 안에 있는 것과 당신이 입력하는 것만 알 뿐이다. Model Context Protocol(MCP)은 그 벽을 허물고 에이전트가 실제 도구, 즉 데이터베이스, GitHub, 모니터링 대시보드, 디자인 파일에 접근하도록 해 주는 방법이다.

이 가이드는 MCP가 무엇인지 설명하고 Claude Code에 첫 서버를 연결하는 과정을 안내한다. 동일한 개념이 Cursor와 Copilot에도 그대로 적용된다.

MCP가 실제로 무엇인가

MCP는 개방형 표준이다 — AI 에이전트와 이미 사용 중인 시스템 사이의 범용 어댑터라고 생각하면 된다. 모든 도구가 저마다 모든 에이전트와 대화하는 방식을 새로 만드는 대신, 도구는 하나의 MCP 서버를 제공하고, MCP를 인식하는 모든 에이전트(Claude, Cursor, Copilot)가 여기에 연결할 수 있다. 2026년 내내 "MCP"가 어디서나 보였던 이유가 바로 이것이다. MCP는 에이전트가 말만 하는 것이 아니라 실제 작업을 하도록 만드는 배관이다.

좋은 판단 기준 하나: 다른 도구에서 데이터를 채팅 안으로 복사하고 있는 자신을 발견할 때마다 서버를 연결하라. Sentry에서 오류 로그를, 혹은 Jira에서 티켓 상세 내용을 계속 붙여넣고 있다면, 그것은 MCP 서버가 그 수고를 덜어 줄 수 있다는 신호다.

두 종류의 서버

만나게 될 두 가지 유형이 있다:

• 원격(HTTP) 서버는 클라우드에서 실행되며 네트워크를 통해 연결한다 — Notion, GitHub, 그리고 대부분의 SaaS 도구가 이 방식으로 동작한다. 이것이 권장되는 기본값이다.
• 로컬(stdio) 서버는 자신의 컴퓨터에서 프로세스로 실행된다 — 로컬 데이터베이스 드라이버처럼 시스템에 직접 접근해야 하는 경우에 유용하다.

첫 서버 추가하기

핵심 명령어는 claude mcp add이다. 원격 HTTP 서버의 기본 형태는 다음과 같다:

claude mcp add --transport http <name> <url>

구체적인 예시 — 에이전트가 페이지를 읽고 업데이트할 수 있도록 Notion을 연결한다:

claude mcp add --transport http notion https://mcp.notion.com/mcp

서버에 인증이 필요하면 토큰을 헤더로 전달한다:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

로컬 서버의 경우, -- 뒤에 오는 모든 것이 서버를 시작하는 명령어다:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

그 --가 중요하다: Claude 자체의 플래그와 서버를 실행하는 명령어를 구분해 주므로, 서버용으로 의도한 --port가 Claude 옵션으로 파싱되지 않는다.

추가한 뒤에는 무엇을 연결했는지 확인한다:

claude mcp list        # 모든 서버와 상태 보기
claude mcp get notion  # 서버 하나의 상세 정보

Claude Code 세션 안에서 /mcp 명령어는 실시간 연결 상태를 보여 주며, OAuth를 사용하는 서버의 경우 로그인할 수 있게 해 준다.

올바른 범위 선택하기

서버를 추가할 때 --scope 플래그로 누가 그것을 볼 수 있는지 결정한다:

• local(기본값) — 오직 당신, 오직 이 프로젝트.
• project — 저장소에 커밋되는 .mcp.json 파일을 통해 팀 전체와 공유된다. 온보딩에 좋다: 새 팀원이 저장소를 클론하면 에이전트가 이미 팀의 도구를 알고 있다.
• user — 당신의 컴퓨터에 있는 모든 프로젝트에서 사용할 수 있다.

팀 데이터베이스나 이슈 트래커에는 보통 project 범위가 원하는 것이다. 개인 API 키의 경우 저장소에 절대 들어가지 않도록 local이나 user로 유지하라.

안전하게 하기

MCP는 에이전트에게 실제 접근 권한을 준다는 바로 그 이유로 강력하다 — 그래서 약간의 주의가 큰 도움이 된다:

• 연결하기 전에 서버를 신뢰하라. 외부 콘텐츠를 가져오는 서버는 프롬프트 인젝션 위험에 당신을 노출시킬 수 있다. 이는 가져온 데이터 속 악의적인 텍스트가 에이전트를 조종하려 하는 것이다. 알아볼 수 있는 벤더의 공식 서버만 사용하라.
• 자격 증명의 범위를 좁게 하라. 작업이 읽기만 필요하다면 서버에 읽기 전용 또는 최소 권한 키를 부여하라. 이것이 바로 Microsoft가 엔터프라이즈 Dataverse 플러그인에 담아 놓은 원칙이다 — 에이전트는 부여받은 역할이 허용하는 것만 볼 수 있다.
• 공유 설정에서 비밀 정보를 배제하라. 토큰은 환경 변수나 local 범위에 넣고, 커밋되는 project 범위의 .mcp.json에는 절대 넣지 마라.
• 무엇을 할 수 있는지 검토하라. 연결한 뒤 /mcp를 열고 서버가 노출하는 도구들을 훑어보아 뜻밖의 일이 없도록 하라.

얻게 되는 것

서버가 연결되면 작업 방식의 변화가 즉시 나타난다. "제가 붙여넣은 스키마는 여기 있습니다" 라고 하는 대신, 이렇게 물을 수 있다: "우리 Postgres 데이터베이스에서 가장 최근에 가입한 10명을 찾아서 각각에게 피드백 세션 초대장 초안을 작성해 줘." 에이전트는 데이터베이스를 쿼리하고, 결과를 읽고, 이메일 초안을 작성한다 — 이 모든 것이 하나의 흐름 안에서 이루어진다. 마침내 당신의 작업이 실제로 존재하는 시스템에 접근할 수 있게 되었기 때문이다.

가장 자주 붙여넣는 도구를 위한 서버 하나로 시작하라. 그 단일 연결 하나가 대개 그것에 대해 아무리 많이 읽는 것보다 더 빠르게 그 가치를 분명하게 만들어 준다.