통합(Integrations) 카탈로그를 열면 Figma, GitHub, n8n, Obsidian, Excel 등 수십 개의 타일이 보입니다. 이를 보면 마치 에이전트가 이미 이 도구들을 다룰 수 있는 것처럼 느껴집니다. 하지만 이는 잘못된 결론입니다. 목록에 항목이 있다는 것은 단지 누군가가 언젠가 그 항목을 목록에 추가했다는 사실만을 증명할 뿐입니다. Claude 에이전트가 필요한 권한을 가지고, 안전하며, 관찰 가능한 결과를 내며, 특정 도구를 통해 하나의 구체적인 작업을 완료할 수 있을까요? 로고 카탈로그는 이 질문에 답해주지 않습니다.

따라서 이 글의 관점은 다음과 같습니다. 도구는 '혹시 모르니까'라는 생각으로 한꺼번에 연결하는 것이 아니라, 검증된 하나의 시나리오에 따라 하나씩 연결해야 합니다. 아래에는 여기서 '카나리아(canary)'라고 부르는 한 가지 검증 과정의 빌드 다이어리(build diary)가 담겨 있습니다. 에이전트에 대한 일반적인 이론이 아니라, 하나의 도구를 가져와서, 하나의 명확한 권한을 부여하고, 하나의 입력을 제공하며, 하나의 동작을 수행한 뒤, 결과가 모델의 상상(hallucination)이 아니라 정확히 해당 도구로부터 왔는지 확인하는 좁은 범위의 테스트입니다.

"ии агент claude", "ии агент клод", "ai агент claude", "агент для ai claude" 및 "ии агент на базе claude"와 같은 검색어들은 모두 동일한 것을 설명합니다. 즉, 스스로 단계를 수행하는 Claude 모델과 도구 및 권한의 결합입니다. 이후 본문에서는 이를 Claude 에이전트로 지칭하며, 검색에서 나타나는 "клод агент"나 "claude агент"와 같은 일상적인 표현들도 동일한 의미를 나타냅니다.

통합 카나리아의 구성 요소

카나리아는 네 가지 필수 요소가 포함된 최소 단위의 재현 가능한 실행입니다. 이 중 하나라도 누락되면 해당 시나리오는 검증된 것으로 간주하지 않습니다.

권한(Permission). 도구가 연결되어 있으며 에이전트에게 명시적으로 허용되었습니다. 단순히 "모델이 원칙적으로 도구를 호출할 수 있다"는 것이 아니라, 해당 서버와 해당 작업 세트에 대한 고정된 접근 규칙이 있어야 합니다.

입력(Input). 구체적인 입력 세트가 필요합니다: 파일, 브랜치(branch), 셀 범위, 객체 ID 등입니다. "내 리포지토리(repository)에서 작업해줘"와 같은 추상적인 문구가 아니라, 내일도 똑같이 재현할 수 있는 정확한 입력이어야 합니다.

동작. 하나의 도구 동작은 읽기, 생성, 편집 중 하나입니다. 여기서 중요한 것은 읽기와 상태 변경을 구분하는 것입니다. Anthropic의 MCP(Model Context Protocol) 문서(Claude Docs, 2026년 7월 18일 접속)에 따르면, 호출하는 측에서 읽기와 상태를 변경하는 작업을 구분할 수 있도록 모든 도구는 반드시 readOnlyHint 및 destructiveHint 어노테이션(annotation)을 선언해야 합니다.

결과 확인. 관찰 가능한 종료. Claude Code 문서(2026년 7월 18일 접속)에 따르면, 방금 연결된 MCP 도구를 처음 호출할 때 에이전트는 명시적인 권한을 요청하며, 성공적인 호출은 출력 결과에 서버 이름이 표시됩니다. 이 표시는 응답이 모델의 내장된 지식(built-in knowledge)에서 온 것이 아니라 도구로부터 왔음을 확인하는 문서화된 방법입니다.

이 네 가지 요소는 "도구—권한—관찰" 형식의 실행 로그를 제공합니다. 이것이 바로 작동하는 결합(combination)과 단순히 카탈로그에 적힌 한 줄의 문구를 구분 짓는 유일한 산출물(artifact)입니다. 그 외의 모든 것은 단지 약속에 불과합니다.

여기서 서두르다 보면 혼동하기 쉬운 두 가지, 즉 언어 모델 자체에 대한 접근과 에이전트에 대한 도구 통합(integration)을 구분해야 합니다. 모델 부분은 호환 가능한 API로서 확인할 수 있습니다. OpenAI 또는 Anthropic 프로토콜을 지원하는 클라이언트는 현재 플랫폼을 통해 사용할 수 있는 모델 범위 내에서, SDK의 키(key)와 기본 주소(base address)를 변경함으로써 provod.ai에 연결할 수 있습니다.

base_url = "https://api.provod.ai/v1"

러시아에서 결제하는 사용자의 경우, 동일한 플랫폼에서 VPN이나 해외 카드 없이 루블화 잔액을 충전할 수 있습니다: 카드, SBP(Faster Payments System) 또는 계좌 이체를 통해 가능합니다. 이어지는 본문에서는 모델에 대한 호환 가능한 접근과 도구 통합(Integration)이 왜 서로 다른 테스트인지 보여줍니다.

Claude 에이전트에 도구를 연결하는 방법

에이전트의 내부(Under the hood)에는 Claude SDK, 즉 Claude Agent SDK가 있으며, Claude Code는 이를 기반으로 구축되었습니다. 문서(Claude Code Docs, 접속일 2026년 7월 18일)에 따르면, SDK는 Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, AskUserQuestion과 같은 내장 도구 세트를 기본적으로 제공합니다. 이 세트 이외의 모든 것은 MCP(Model Context Protocol) 서버를 통해 별도로 추가됩니다. 따라서 문서에서 'SDK 도구'와 'MCP를 통해 연결된 도구'는 서로 다른 범주에 속하며, 이것이 사람들이 가장 먼저 혼동하는 부분입니다.

에이전트 자체는 CLI(Command Line Interface)로 설치되며, 검색 시 설치 방법은 "claude npm" 또는 "npm claude"로 나타납니다. 두 표현 모두 명령줄 유틸리티를 설치하는 동일한 방법을 의미합니다. IDE에서는 플러그인 형태로 제공됩니다. 일반적인 검색어는 "claude ide"이며, JetBrains 제품군의 경우 "claude intellij idea" 또는 "intellij idea claude", PhpStorm의 경우 "claude phpstorm plugin"과 같이 구체적으로 검색합니다. "vs code에 claude 연결하는 법" 또는 "vs code에서 claude 연결하는 법"과 같은 검색어는 VS Code 에디터와 관련이 있습니다. 여기서 중요한 점은 IDE에 플러그인을 설치하는 것이 아직 외부 도구의 작동하는 통합(Integration)을 의미하지는 않는다는 것입니다.

외부 도구를 연결하는 문서화된 방법은 CLI 명령어를 사용하는 것입니다. 원격(Hosted) 서버의 경우:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

로컬 stdio 서버의 경우:

claude mcp add <name> -- <command>

서버는 세 가지 스코프(scope) 중 하나에 기록되며, 스코프는 추가되는 시점에 고정됩니다: local (기본값, 해당 프로젝트에만 적용, ~/.claude.json), project (.mcp.json, 버전 관리 시스템을 통해 공유), 그리고 user (~/.claude.json, 모든 프로젝트). 이는 "Claude에 MCP를 어떻게 연결하나요?"라는 일상적인 질문에 대한 답변입니다. 카탈로그에서 가져오는 마법 같은 것이 아니라, 명시적인 전송 방식(transport)과 주소를 가진 단 하나의 명령어로 이루어집니다.

연결이 실제로 작동하는지 확인하는 방법

상태는 두 가지 방법으로 확인할 수 있습니다: 셸(shell)에서 claude mcp list를 실행하거나, 세션 내부에서 /mcp를 입력하는 것입니다. 문서(Claude Code Docs, 접속일 2026년 7월 18일)에 따르면, 이 명령들은 다음 여섯 가지 상태 중 하나를 반환합니다: ✔ Connected, ! Connected · tools fetch failed, ! Needs authentication, ✘ Failed to connect, ✘ Connection error, ⏸ Pending approval (run claude to approve). ✔ Connected를 제외한 다섯 가지 상태는 각각 로고 목록이 보여주지 않는 별개의 장애 지점(point of failure)입니다.

권한(permissions)은 생각보다 더 중요합니다. SDK의 권한 평가 순서는 다음과 같이 고정되어 있으며 문서화되어 있습니다 (Claude Code Docs, 접속일 2026년 7월 18일): (1) hooks, (2) 거부 규칙 (deny-rules, disallowed_tools/settings.json), (3) 확인 규칙 (ask-rules), (4) 권한 모드 (permission mode), (5) 허용 규칙 (allow-rules, allowed_tools/settings.json), (6) 콜백(callback) canUseTool. 거부 규칙은 bypassPermissions 모드에서도 도구 사용을 차단합니다. 또한, 서버가 _meta["anthropic/requiresUserInteraction"]를 설정한 MCP 도구는 허용 규칙(allow-rule)과 일치하더라도 항상 콜백으로 넘어갑니다 (소스에서 이 어노테이션은 Claude Code v2.1.199 이상을 요구한다고 표시되어 있으므로, 사용 중인 버전에서 별도로 확인하십시오).

두 가지 규칙 함정이 있습니다. 첫 번째는 allowed_tools가 나열된 도구들만을 승인할 뿐이라는 점입니다. 나열되지 않은 도구들이 사라지는 것이 아니라, 활성 권한 모드로 넘어가 버립니다. 반면 disallowed_tools=["ToolName"]은 도구 정의 자체를 제거하므로 에이전트가 호출을 시도조차 하지 않습니다. MCP 허용(allow) 글로브(glob)의 경우 mcp__<server>__와 같은 리터럴 접두사(예: mcp__github__get_*)를 요구하며, 앵커되지 않은 allowed_tools=["mcp__*"]는 문서상에서 무시되며 시작 시 경고가 발생합니다. 두 번째 함정은 더 심각합니다. bypassPermissions 모드는 이 단계에 도달한 거의 모든 호출을 자동으로 승인하며, 문서는 "Claude has full system access in this mode... use with extreme caution(이 모드에서 Claude는 시스템에 대한 전체 액세스 권한을 가집니다... 극도로 주의하여 사용하십시오)"라고 직접 경고합니다. 게다가 allowed_tools는 이 모드에서 범위를 제한하지 않습니다. 즉, 나열된 도구뿐만 아니라 모든 도구가 승인됩니다. bypassPermissions에서의 카나리(Canary) 테스트는 권한이 올바르게 설정되었음을 증명하는 것이 아니라, 사실상 권한이 존재하지 않음을 증명할 뿐입니다.

작동하는 모델 API가 도구 통합을 확인하지 못하는 이유

모델 API 수준에는 별도의 경로인 Messages API 내의 "MCP 커넥터(MCP connector)"가 있습니다. 플랫폼 문서(Claude Platform Docs, 접속일 2026년 7월 18일)에 따르면, 이는 구형인 mcp-client-2025-04-04를 대체한 베타 헤더 mcp-client-2025-11-20를 통해 활성화되며, Claude Code 클라이언트나 Agent SDK 없이도 API가 직접 원격 HTTP/SSE MCP 서버를 호출할 수 있게 해줍니다. 이는 OAuth Bearer 토큰을 지원하지만, 로컬 stdio 서버는 명시적으로 지원하지 않습니다.

쉽게 간과할 수 있는 결론은, 모델 API와 MCP 서버 간의 작동하는 연결 자체만으로는 Claude 에이전트의 도구 통합(Integration)을 확증할 수 없다는 점입니다. 이는 서로 다른 두 개의 문서 영역에 속한, 아키텍처적으로 다른 두 가지 메커니즘입니다. "목록에 통합 항목이 있으니 에이전트 시나리오가 작동할 것이다"라는 논쟁적인 기본 가정은 구체적인 상황에서 무너집니다. 호환되는 모델 API와 연결된 도구는 각각 별도의 카나리(Canary, 검증 지표)를 통해 확인되어야 합니다.

GitHub를 예로 든 한 번의 실행

구체적인 도구를 하나 들어보겠습니다. 공식 원격 GitHub MCP 서버(https://api.githubcopilot.com/mcp/에서 호스팅됨)는 벤더 문서(GitHub, 접속일 2026년 7월 18일)에 따르면, 로컬 설치나 PAT(Personal Access Token) 없이도 기본적으로 OAuth를 통한 원클릭 로그인을 지원합니다. 하지만 OAuth를 완전히 지원하지 않는 호스트의 경우, 개인 액세스 토큰(Personal Access Token)으로도 설정할 수 있습니다. 이는 "인증이 설정됨"과 "특정 도구 호출이 관찰됨"이라는 두 가지 서로 다른, 별도로 검증 가능한 사실이 공존하는 정확한 사례입니다. 여기서 GitHub 문서의 주의사항이 등장합니다. 완전한 원격 OAuth는 현재 모든 곳에서 사용 가능한 것은 아니며(그들의 설명에 따르면 호스트에 따라 다름), 따라서 다른 호스트에서는 최신 지원 여부를 다시 확인해야 합니다.

"Claude를 GitHub에 연결하는 방법" 또는 "Git을 Claude에 연결하는 방법"에 대한 질문은 카탈로그의 로고가 아니라 다음 표를 통해 답변됩니다.

네 개의 셀이 모두 채워지면 연결이 확인된 것입니다. 통합 맵(Integration Map)은 이 요소만을 확인된 것으로 표시합니다. 나머지 도구들은 각자의 카나리 테스트를 통과할 때까지 확인되지 않은 상태로 남습니다. 이것이 바로 정직한 "연결 맵(Connection Map)"입니다. 관찰된 결과가 있는 곳은 녹색으로, 그 외 나머지는 회색으로 표시됩니다.

어떤 질문들이 들어오며, 왜 그 질문들은 본질을 벗어나 있는가

사람들이 검색 시 사용하는 실제 문구들을 살펴보는 것이 유용합니다. 이것은 벤더(vendor)에 대한 사실이 아니라 입력 문자열의 코퍼스(corpus)이며, 카나리(canary)가 필요한 이유는 바로 이러한 각각의 문자열을 "작동하는 것 같다"는 상태에서 관찰 가능한 결과로 바꾸기 위함입니다.

디자인 및 Figma. "claude를 figma에 연결하는 방법", "claude를 피그마에 연결하는 방법", "클로드를 피그마에 연결하는 방법"과 같은 질문이 들어오며, "claude design 어떻게 연결하나"라고 묻거나 "frontend design claude plugin"을 검색합니다. 때로는 채팅창에 claude plugin install figma@claude-plugins-official과 같이 이미 완성된 문자열이 들어오기도 하는데, 사용자들은 이를 현재 문서와 대조하지 않고 그대로 붙여넣습니다. 바로 이러한 붙여넣기 된 문자열들이 구식이고 확인되지 않은 연결 방식의 후보들입니다. 문서화된 경로는 claude mcp add로 유지되고 있지만, 채팅에서 가져온 문자열은 이를 바탕으로 프로세스를 구축하기 전에 반드시 카나리(canary)를 통해 검증해야 합니다.