Claude가 내부 API를 쓰게 만드는 방법은 하나가 아닙니다. MCP는 재사용 가능한 tool contract가 필요할 때 유용하지만, API 설계, 권한, 승인, 감사 로그를 대신하지 않습니다.
먼저 누가 실행을 소유하는지 결정해야 합니다. 애플리케이션이 이미 prompt, state, user session, tool 실행, 감사 로그를 갖고 있다면 direct Claude API tools가 보통 가장 짧은 길입니다. 여러 Claude surface가 같은 내부 toolset을 써야 한다면 좁은 remote MCP server를 만들고 Claude가 실제로 필요한 작업만 노출하는 편이 낫습니다.
2026년 6월 1일 기준 Anthropic 문서는 direct tool use, Messages API MCP connector, Claude Code MCP, Claude custom connectors를 별도 경로로 설명합니다. 따라서 Claude MCP 내부 도구 API 통합을 설계할 때는 아래처럼 먼저 route를 나누는 것이 좋습니다.
| 통합이 필요한 상황 | 먼저 볼 경로 | 이유 |
|---|---|---|
| 한 앱이 prompt, state, execution, audit를 모두 소유한다 | Direct Claude API tools | 앱이 tool_use를 받고 내부 작업을 실행한 뒤 tool_result를 반환할 수 있습니다. |
| Messages API가 재사용 가능한 remote toolset을 호출해야 한다 | Claude API MCP connector | 앱 내부에 별도 MCP client를 두지 않고도 reachable remote MCP server에 연결할 수 있습니다. |
| 여러 Claude client가 같은 내부 tool contract를 공유해야 한다 | Custom MCP server | API 팀이 client별 adapter 대신 하나의 제한된 tool interface를 운영할 수 있습니다. |
| 개발자가 로컬 repo, 파일, command workflow를 써야 한다 | Claude Code MCP | local stdio, project scope, /mcp 제어는 developer workflow branch에 속합니다. |
| Claude.ai 또는 Desktop의 human workflow에 승인된 connector가 필요하다 | Custom connector | user-facing connector route이며 plan, permission, network boundary가 따로 있습니다. |
| 장시간 실행되는 hosted agent runtime 자체가 문제다 | Managed Agents | 단순 tool access가 아니라 hosted session runtime이 병목일 때만 비교합니다. |
중단 규칙은 단순합니다. MCP가 가능하다는 이유만으로 MCP server를 만들지 마세요. 재사용, connector ownership, cross-client consistency가 extra server, auth, review surface를 감당할 만큼 중요할 때 MCP를 선택합니다.
Direct Claude API Tools와 MCP의 경계
가장 짧은 경로는 Claude API tool use입니다. 앱이 tool definition을 보내고, Claude가 tool_use block을 반환하면, 앱 코드가 내부 작업을 실행한 뒤 tool_result를 돌려줍니다. 한 앱이 prompt, user session, authorization check, tool execution, retry, audit log, response shaping을 모두 소유할 때 이 방식으로 충분합니다.
MCP는 tool contract가 한 앱보다 오래 살아야 할 때 값이 있습니다. 내부 검색, 티켓, billing, deployment, reporting 도구를 여러 Claude surface에서 같은 이름과 schema로 쓰게 만들고 싶다면 custom MCP server가 맞는 추상화일 수 있습니다. 이때 server는 API 팀이 소유하는 제한된 interface가 됩니다. Claude client는 tool을 소비하고, API 팀은 name, schema, auth, output limit, policy를 관리합니다.
| 판단 지점 | Direct Claude API tools | MCP를 만들거나 노출 |
|---|---|---|
| Runtime owner | 한 앱이 이미 loop를 실행한다 | 여러 client가 같은 tool contract를 써야 한다 |
| Tool execution | 앱이 내부 호출을 실행하고 tool_result를 반환한다 | remote server가 protocol boundary 뒤에서 실행을 소유한다 |
| Auth boundary | 기존 app session과 service account로 충분하다 | connector-level auth, headers, allowlists, per-tool ownership이 중요하다 |
| Change control | 한 product team이 integration을 바꿀 수 있다 | API/platform team이 여러 Claude client용 stable contract를 원한다 |
| Operational cost | 첫 버전은 작게 유지한다 | 추가 server, deployment, review, monitoring surface를 받아들인다 |
실무 기준은 재사용성과 ownership입니다. 도구가 한 product workflow 안에서만 쓰이면 direct tools가 보통 더 깨끗합니다. 같은 작업이 Claude API calls, Claude.ai connectors, Claude Code projects, future internal agents까지 확장되어야 한다면 MCP가 움직이는 부품을 늘릴 만큼의 이유가 생깁니다.
MCP tool을 backend endpoint의 얇은 복사본으로 만들지 않는 것이 중요합니다. Claude는 전체 admin API가 필요하지 않습니다. Claude가 추론할 수 있는 작업형 capability가 필요합니다. 예를 들어 search_customer_ticket, summarize_invoice_status, create_refund_draft, open_deployment_incident처럼 user outcome이 보이는 이름이 더 안전합니다. 이름, description, schema, returned content는 Claude가 reasoning하는 interface의 일부이며 MCP tool specification에서도 이 구조가 핵심입니다.
내부 API는 좁은 wrapper로 설계하기
안전한 Claude internal tool integration은 wrapper layer에서 시작합니다. wrapper는 기존 internal API를 작은 tool contract로 바꿉니다. 입력은 명시적이어야 하고, 출력은 제한되어야 하며, credential은 scoped 되어야 하고, 실패 동작은 예측 가능해야 합니다. 목표는 engineer에게 복잡성을 숨기는 것이 아닙니다. Claude가 실제 작업을 끝낼 만큼 충분하지만 review 가능한 action surface를 주는 것입니다.
먼저 user outcome을 정하고, 그 outcome을 만족하는 가장 작은 tool로 역산합니다.
| Outcome | 나쁜 tool shape | 더 나은 tool shape |
|---|---|---|
| 고객 billing 상태 확인 | arbitrary path와 body를 받는 call_internal_billing_api | customer_id, status fields, last invoice, next action만 반환하는 get_customer_billing_summary |
| refund 준비 | raw JSON을 받는 admin_mutation | draft id를 만들고 human approval 전에는 실행하지 않는 create_refund_draft |
| incident 조사 | unrestricted text와 time range를 받는 query_logs | service, time window, limit, count, sample lines가 있는 summarize_incident_errors |
| CRM note 업데이트 | endpoint free-form access가 가능한 write_crm | account id, note text, reason, actor, audit id를 요구하는 append_account_note |
wrapper는 Claude가 받지 말아야 할 것도 결정해야 합니다. secret은 server-side에 남겨야 합니다. token, raw PII, full database row, unrestricted logs는 reader workflow가 정말 요구하고 policy가 허용할 때만 반환해야 합니다. Claude에게 필요한 것이 결정이라면 source id, count, timestamp, 작은 sample을 포함한 decision-ready summary가 더 좋습니다.
처음부터 compact result design을 적용하세요. token cost 때문만은 아닙니다. 큰 internal API payload는 Claude가 noisy field, irrelevant row, 반복 metadata를 검사하게 만들어 tool use reliability를 낮춥니다. 더 나은 결과는 짧고 typed 되어 있으며 다음 action이 보입니다.
json{ "customer_id": "cus_123", "billing_status": "past_due", "open_invoice_count": 2, "latest_invoice": { "id": "inv_789", "amount_due_usd": 42.5, "due_date": "2026-06-03" }, "recommended_next_action": "ask customer to update payment method", "source_records": ["inv_789", "ticket_456"] }
wrapper는 위험한 action을 안전한 read보다 느리게 만들어야 합니다. read-only summary는 바로 반환할 수 있습니다. write는 보통 draft를 만들고, 승인자를 요구하며, 누가 승인했는지 기록해야 합니다. tool에는 reason field, idempotency key, preview response, 그리고 domain이 지원한다면 rollback 또는 cancel path가 있어야 합니다.
Remote Connector 경계: API MCP Connector, Custom Connectors, Network Reach
Claude API MCP connector는 local Claude Code MCP server와 같은 것이 아닙니다. 이 경로는 Messages API가 remote MCP server에 직접 연결하도록 해주지만, server는 Streamable HTTP 또는 SSE를 통해 HTTP로 reachable해야 합니다. local stdio server를 이 API route에 그대로 붙일 수 없습니다.
2026년 6월 1일 기준 production plan 가까이에 두어야 할 구현 boundary는 아래와 같습니다.
| Boundary | 현재 planning consequence |
|---|---|
| Beta header | request에는 현재 anthropic-beta: mcp-client-2025-11-20이 필요합니다. 오래된 header name은 재검증 전까지 stale로 봅니다. |
| Transport | API connector에는 reachable remote HTTP/SSE MCP server를 씁니다. local stdio Claude Code command를 이 path에 복사하지 않습니다. |
| Capability scope | connector는 현재 MCP tool calls를 지원하는 경로이지 모든 MCP primitive를 위한 일반 tunnel이 아닙니다. |
| Data retention | Anthropic 문서는 MCP connector가 ZDR에 포함되지 않는다고 설명하므로 sensitive-tool policy review가 필요합니다. |
| Tool control | allowlist, denylist, connector-level control로 model이 task에 필요한 tool만 보게 해야 합니다. |
Claude.ai 또는 Claude Desktop용 custom connectors는 또 다른 user-facing route입니다. 역시 remote MCP를 사용하지만 product surface, approval model, plan availability, admin control이 backend Messages API integration과 다릅니다. Anthropic cloud infrastructure가 connector에 reach할 수 있어야 하므로 private-network assumption은 design accepted 전에 테스트해야 합니다.
내부 API에서는 network reach가 사소한 deployment detail이 아닙니다. MCP server가 어디에 배포되는지, 어떤 firewall rule이 필요한지, OAuth 또는 service token을 어떻게 발급하는지, tenant boundary를 어떻게 지키는지, tool access를 누가 승인하는지가 모두 이 사실에서 결정됩니다. 민감한 내부 system에 닿는 connector는 company data를 읽거나 바꿀 수 있는 external integration과 같은 수준의 security review를 받아야 합니다.
코드를 쓰기 전에 이 boundary table을 먼저 확인하세요.
| 질문 | Direct tools | API MCP connector | Custom connector |
|---|---|---|---|
| 누가 내부 system에 닿는가 | application backend | Claude API path에서 reachable한 remote MCP server | Claude user surface에서 reachable한 remote MCP server |
| Auth는 어디서 enforce되는가 | app session, service account, tool executor | MCP server, connector config, headers, internal policy | connector auth, user/admin approval, MCP server, internal policy |
| 좋은 첫 사용처 | product-owned workflow | Messages API용 shared internal toolset | 승인된 remote tool이 필요한 human Claude workflow |
| 첫 production risk | app code 안에 숨은 broad tool execution | 너무 많은 tool 노출 또는 너무 큰 data 반환 | user-facing permission, write action, prompt-injection risk |
remote MCP server라면 developer convenience script가 아니라 production integration처럼 설계해야 합니다. health check, request logging, auth verification, rate limit, schema test, safe failure response가 필요합니다. server가 한 개발자의 local helper일 뿐이라면 API connector로 승격하지 말고 Claude Code branch에 남겨두는 편이 맞습니다.
Claude Code와 Desktop은 로컬 workflow branch
Claude Code MCP는 local developer workflow에 매우 적합합니다. repository tool, project-local script, internal docs, issue tracker, database read helper, browser verification, team-specific development utility처럼 개발자가 자신의 작업 환경에서 쓰는 tool에 맞습니다. local stdio server가 의미 있는 곳도 이 branch입니다. 현재 Claude Code MCP docs와 CLI help는 local, project, user scope를 나누고, 현재 CLI syntax는 stdio, sse, http transports를 지원합니다.
그렇다고 Claude Code가 모든 internal tool integration의 runtime이 되는 것은 아닙니다. production app이 Messages API를 호출한다면 developer laptop의 Claude Code setting은 app tool surface를 정의하지 않습니다. local stdio server가 Claude Code에서 동작한다는 사실은 local workflow branch를 증명할 뿐입니다. 같은 tool이 remote API connector에서 reachable하다는 증거가 아닙니다.
reader job이 local이라면 Claude Code MCP를 씁니다.
bashclaude mcp add --scope project support-search --transport stdio -- ./scripts/support-search-mcp claude mcp list
reader job이 backend 또는 cross-client라면 remote route를 씁니다.
bashclaude mcp add --scope project support-search https://mcp.example.com/mcp
두 branch는 문서에서도 분리해야 합니다. local MCP server는 local file system을 읽고, local command를 실행하고, developer-specific credential에 의존할 수 있습니다. remote MCP server는 deployment, reachable networking, auth, observability, stricter public interface가 필요합니다. 이 가정을 섞으면 demo에서는 작동했지만 production approval을 받을 수 없는 통합이 됩니다.
Claude Code MCP server 선택 자체가 문제라면 workflow-first Claude Code best MCP servers를 보세요. active MCP server가 너무 많거나 tool return이 context를 부풀린다면 Claude Code MCP context overload 정리 경로가 더 맞습니다. credential routing, environment variables, provider base URL이 혼란스럽다면 Claude Code API configuration을 먼저 확인하는 편이 낫습니다.
Production Safety Checklist
내부 tool은 safety ladder를 따라 이동해야 합니다. 첫 버전은 Claude가 제한된 data를 읽고 유용한 summary를 반환할 수 있는지 증명하는 단계여야 합니다. write access는 preview, approval, audit, rollback behavior가 지루할 만큼 안정된 뒤에 붙입니다.
| Gate | Pass condition | Stop if... |
|---|---|---|
| Tool scope | 각 tool이 하나의 user outcome과 하나의 좁은 internal operation에 매핑된다 | tool이 arbitrary endpoint, SQL, shell, mutation input을 받는다 |
| Credential scope | credential은 server-side, least-privilege, environment별 분리 상태다 | Claude가 secret을 보거나 broad admin credential을 재사용할 수 있다 |
| Read-only proof | read가 compact, decision-ready result와 source id를 반환한다 | read가 raw dump, secret, unbounded result set을 반환한다 |
| Write preview | write tool이 실행 전 draft 또는 preview를 만든다 | write가 human 또는 policy approval 없이 즉시 실행된다 |
| Approval path | risky action에는 approver, reason, durable audit id가 있다 | approval이 prompt text 안에만 존재한다 |
| Audit log | 모든 tool call이 actor, user, tool, input summary, output summary, result id를 기록한다 | Claude가 무엇을 시도했고 실제로 무엇이 바뀌었는지 복원할 수 없다 |
| Output budget | result에 limit, pagination, summary, file handle이 있다 | 한 번의 call이 log, row, full document로 context를 넘치게 할 수 있다 |
| Prompt-injection guard | ticket, doc, web page, user content에서 온 tool result를 untrusted data로 취급한다 | tool output이 policy override나 write tool 호출을 지시할 수 있다 |
Prompt injection은 web browsing만의 문제가 아닙니다. support tickets, CRM notes, docs, emails, Slack exports, database comments, customer-uploaded files에도 adversarial instruction이 들어갈 수 있습니다. wrapper는 retrieved content를 data로 label하고 system policy와 분리해야 하며, structured summary로 충분하다면 불필요한 raw text를 반환하지 않는 편이 좋습니다.
Approval design은 action의 위험도와 맞아야 합니다. low-risk read summary는 normal auth와 logging만으로 충분할 수 있습니다. refund, deployment, permission change, account suspension, database mutation은 preview, approval record, final state verification이 필요합니다. 내부 domain이 rollback을 제공하지 못한다면 approval 전에 tool이 그 사실을 말해야 합니다.
Implementation Sketch
Direct tools로 시작하든 MCP로 시작하든 구현 pattern은 같습니다. narrow tool을 정의하고, trusted code에서 실행하며, compact output을 반환하고, 시도를 log합니다. 차이는 tool contract가 어디에 살고 어떤 runtime이 그것을 호출하느냐입니다.
Direct Claude API tools에서는 application loop가 execution을 소유합니다.
tsconst tools = [ { name: "get_customer_billing_summary", description: "Return a compact billing summary for a support-approved customer id.", input_schema: { type: "object", properties: { customer_id: { type: "string" }, reason: { type: "string" } }, required: ["customer_id", "reason"] } } ]; // 1. Send tools with the request. // 2. When Claude returns tool_use, verify caller permission. // 3. Call the internal API with a scoped service credential. // 4. Return a compact tool_result and write an audit entry.
Remote MCP server에서는 API team이 server contract를 소유합니다. server는 tool definition과 handler를 노출하고, Claude client는 선택된 product surface를 통해 연결합니다. 첫 server는 일부러 지루하게 만드는 편이 좋습니다.
| Server design choice | Better default |
|---|---|
| Tool naming | get_customer_billing_summary처럼 verb plus domain outcome |
| Input schema | required ids, reason fields, time windows, limits, enum values |
| Output schema | summary fields, source ids, next action, warnings, cursor |
| Error handling | raw stack trace 대신 typed domain errors |
| Observability | tool call id, actor id, request id, latency, result size, policy decision |
| Permissions | read-only default, write tools behind explicit approval |
Claude API MCP connector를 쓴다면 server가 제공하는 모든 capability를 노출하지 말고 작은 tool set만 요청하세요. custom connectors를 쓴다면 user-facing consent와 admin control을 따로 검토하세요. Claude Code를 쓴다면 local setup을 올바른 scope에 저장하고 secret을 commit하지 마세요. 같은 internal tool이 나중에는 여러 surface를 지원할 수 있지만 첫 production version은 한 route를 깨끗하게 증명한 뒤 branch를 늘리는 편이 안전합니다.
다음 단계 선택
다음 action은 execution을 소유하는 route에 따라 달라집니다.
| 현재 상황 | 다음 move |
|---|---|
| 한 앱이 workflow를 소유하고 몇 개의 internal read만 필요하다 | compact tool_result payload와 audit log가 있는 direct Claude API tools를 구현합니다. |
| 여러 Claude client가 같은 internal toolset을 필요로 한다 | read-only tools부터 custom MCP server를 설계하고 API MCP connector 또는 approved surface로 연결합니다. |
| 작업이 local developer automation이다 | Claude Code MCP에 남기고 project/user scope를 의도적으로 선택하며 context load를 관리합니다. |
| 작업이 Claude.ai 또는 Desktop의 human workflow다 | local stdio assumption이 아니라 custom connector plan, approval model, network design을 봅니다. |
| 진짜 문제는 long-running hosted runtime이다 | 자체 loop를 만들기 전에 Claude Managed Agents와 route를 비교합니다. |
가장 신뢰할 수 있는 첫 milestone은 read-only tool입니다. model request, tool selection, auth check, internal API call, compact result, audit log, human-visible answer가 한 번에 증명되어야 합니다. 그 다음 tool allowlist, output cap, approval flow, write preview를 추가합니다. 그때서야 같은 contract가 reusable MCP server가 될 만큼 가치 있는지 판단할 수 있습니다.
자주 묻는 질문
Claude를 내부 API에 연결하려면 MCP가 필수인가요?
아닙니다. 한 애플리케이션이 loop를 소유하고 tool call을 직접 실행할 수 있다면 direct Claude API tools만으로 충분한 경우가 많습니다. MCP는 여러 Claude client 또는 connector surface가 같은 tool contract를 공유해야 할 때 유용합니다.
Direct Claude API tools와 Claude API MCP connector는 무엇이 다른가요?
Direct tools에서는 application이 tool_use를 받고 내부 작업을 실행한 뒤 tool_result를 반환합니다. Claude API MCP connector에서는 Messages API가 remote MCP server에 연결되고, 그 server가 tool interface를 소유합니다. connector route는 server와 network boundary를 추가하므로 복잡도를 감당할 이유가 있어야 합니다.
Claude API MCP connector가 local stdio MCP server를 직접 쓸 수 있나요?
직접적으로는 아닙니다. 2026년 6월 1일 기준 Anthropic API connector 문서는 remote HTTP/SSE MCP server를 요구합니다. local stdio는 Claude Code 또는 local Desktop-style workflow에 속하며 Messages API connector path가 아닙니다.
내부 API 전체를 MCP tools로 노출해도 되나요?
권장하지 않습니다. 좁은 schema와 compact output을 가진 task-shaped tools만 노출하세요. broad endpoint caller, arbitrary SQL tool, shell tool, admin mutation tool은 Claude가 안전하게 쓰기도 어렵고 사람이 review하기도 어렵습니다.
Write action은 어떻게 설계해야 하나요?
read-only tools로 시작하세요. write는 먼저 draft 또는 preview tool로 만들고, reason, actor, idempotency key, audit id, verification path가 있는 approval을 요구하는 편이 좋습니다. high-risk action은 prompt가 요청했다는 이유만으로 실행되면 안 됩니다.
MCP tool results가 context size에 영향을 주나요?
네. tool definition, tool call, tool result 모두 context를 늘릴 수 있습니다. output은 짧고 summarized, filtered, paginated 되어야 합니다. Claude에게 raw payload 전체가 필요하지 않다면 handle 또는 source id를 반환하세요.
Claude Code MCP는 어디에 맞나요?
Claude Code MCP는 local developer workflow에 맞습니다. project-scoped tools, local scripts, repo helpers, developer automation에 사용하세요. local Claude Code MCP setup이 backend Messages API connector가 deployed 또는 reachable하다는 증거는 아닙니다.
Production 전에 무엇을 확인해야 하나요?
route owner, server reachability, beta header 또는 connector requirement, auth scope, tool allowlist, read-only result shape, write approval flow, audit logging, output limit, prompt-injection handling을 확인해야 합니다. 하나라도 불명확하다면 read-only pilot에 머무르는 것이 좋습니다.