Claude может работать с внутренним API несколькими способами. MCP полезен, когда нужен переиспользуемый контракт инструментов, но это не замена нормальному API design, авторизации, approval flow и audit log.
Начинайте не с выбора протокола, а с вопроса: кто владеет выполнением. Если ваше приложение уже управляет prompt, user session, state, permission check, tool execution и audit log, direct Claude API tools обычно короче и безопаснее. Если один и тот же внутренний набор инструментов должен использоваться из нескольких Claude-поверхностей, тогда имеет смысл построить узкий удаленный MCP server.
На 1 июня 2026 года документация Anthropic разделяет direct tool use, MCP connector в Messages API, Claude Code MCP и custom connectors. Для планирования держите эти маршруты отдельно:
| Если вашей интеграции нужно... | Начните с... | Почему |
|---|---|---|
| Один app владеет prompt, state, execution и audit | Direct Claude API tools | App получает tool_use, выполняет внутренний вызов и возвращает tool_result, не вынося auth наружу. |
| Messages API должен вызвать переиспользуемый удаленный toolset | Claude API MCP connector | Claude подключается к reachable remote MCP server без отдельного MCP client внутри вашего app. |
| Несколько Claude-клиентов должны делить один контракт внутренних tools | Custom MCP server | API/platform team владеет именами tools, schemas, auth, output limits и review process. |
| Разработчику нужен доступ к локальному repo, scripts или machine workflow | Claude Code MCP | Local stdio, project scope, user scope и /mcp относятся к developer workflow. |
| Human workflow в Claude.ai или Desktop требует утвержденного connector | Custom connector | Это user-facing route с отдельными network, plan, permission и trust boundaries. |
| Главная проблема - hosted long-running runtime | Managed Agents | Используйте только если именно hosted session runtime является задачей, а не просто tool access. |
Stop rule: не стройте MCP server только потому, что MCP доступен. Стройте его, когда reuse, ownership of connector или consistency across clients стоят дополнительного server, auth surface и review surface.
Direct Claude API Tools vs MCP
Самый короткий путь часто находится в обычном Claude API tool use. Приложение передает tool definitions; Claude возвращает tool_use, если ему нужна внешняя возможность; ваш backend проверяет permission, вызывает внутренний сервис и возвращает tool_result. Такой маршрут естественен, когда один app уже владеет loop и несет ответственность за пользователя, tenant, service credential, retries, logging и final response.
MCP становится полезным, когда tool contract должен жить отдельно от одного app. Например, API team хочет, чтобы одинаковые операции search_support_ticket, get_customer_billing_summary, create_refund_draft или summarize_deployment_incident были доступны из Messages API, Claude Code, Claude.ai connector и будущих внутренних agents. Тогда MCP server становится bounded interface, а не модным слоем.
| Решение | Direct Claude API tools | MCP или remote connector |
|---|---|---|
| Runtime owner | Один app уже владеет loop | Несколько клиентов должны делить tool contract |
| Tool execution | App может выполнить вызов и вернуть tool_result | Remote server должен владеть execution behind protocol boundary |
| Auth boundary | App session и service account достаточно | Нужны connector headers, OAuth, allowlist или per-tool permissions |
| Change control | Один product team поддерживает integration | Platform/API team поддерживает stable contract для многих клиентов |
| Operational cost | Первая версия маленькая | Вы принимаете server, deploy, monitoring, review и rollback surface |
Главный порог - reuse plus ownership. Если tool используется только внутри одного product workflow, direct tools почти всегда проще. Если одна и та же operation нужна разным Claude clients, MCP может снизить дублирование и сделать review понятнее.
Не превращайте MCP tools в тонкие копии внутренних endpoints. Claude не нужен весь admin API. Ему нужны task-shaped capabilities: проверить billing state, подготовить refund draft, суммировать последние incident errors, добавить CRM note. Tool name, description, input schema и returned content - это интерфейс, по которому модель принимает решения. Чем шире и неопределеннее инструмент, тем труднее его контролировать.
Спроектируйте узкий wrapper над внутренним API
Безопасная интеграция Claude с внутренними инструментами начинается с wrapper layer. Wrapper превращает существующий API в небольшое количество task-shaped tools с явными inputs, bounded outputs, scoped credentials, predictable errors и audit trail.
Начинайте с результата пользователя, а не со списка endpoints:
| Outcome | Плохая форма tool | Лучшее tool |
|---|---|---|
| Проверить billing status клиента | call_internal_billing_api с arbitrary path и body | get_customer_billing_summary с customer_id, reason, invoice summary и next action |
| Подготовить refund | admin_mutation с raw JSON | create_refund_draft, который возвращает draft id и требует approval перед execution |
| Разобрать incident | query_logs без ограничений | summarize_incident_errors с service, time window, limit, counts и examples |
| Добавить CRM note | write_crm с произвольным endpoint | append_account_note с account id, note, reason, actor и audit id |
Wrapper также решает, что Claude не получает. Secrets остаются server-side. Raw PII, full database rows, unlimited logs, tokens и large documents не должны возвращаться по умолчанию. Если Claude нужен decision, верните decision-ready summary: counts, source ids, timestamps, warnings и небольшие samples.
Compact output - это часть tool design, а не косметика. Большие payloads ухудшают reliability, потому что модель тратит context на шумные поля и повторяющуюся metadata. Хороший result короткий, typed и готовый к следующему шагу:
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"] }
Write actions должны быть медленнее, уже и проверяемее, чем reads. Сначала докажите read-only path. Затем добавьте preview или draft. Только после этого включайте execution behind approval. Для risky actions нужны reason, idempotency key, approval id, actor, final state verification и, где возможно, rollback path. Если rollback невозможен, tool должен сказать это до approval.
Отдельно проектируйте prompt-injection boundary. Tickets, CRM notes, docs, emails, web pages и user-uploaded files могут содержать инструкции для модели. Tool results должны маркировать такие данные как untrusted content и возвращать минимально нужный structured summary, а не полный текст, если он не нужен.
Remote Connector Boundaries: API MCP Connector, Custom Connectors и Network Reach
Claude API MCP connector - это не локальный Claude Code MCP server. Это route для Messages API, через который Claude подключается к remote MCP servers. Server должен быть reachable через HTTP с Streamable HTTP или SSE. Local stdio server не подключается напрямую по этой route.
На 1 июня 2026 года план должен учитывать следующие boundaries:
| Boundary | Planning consequence |
|---|---|
| Beta header | Requests currently require anthropic-beta: mcp-client-2025-11-20; older header names must be reverified before reuse. |
| Transport | API connector expects remote HTTP/SSE. Не вставляйте local stdio command из Claude Code в этот путь. |
| Capability scope | Connector currently supports MCP tool calls, not every possible MCP primitive. |
| Data retention | Docs state the MCP connector is not covered by ZDR, so sensitive data needs explicit review. |
| Tool control | Use allowlists, denylists и toolset controls, чтобы Claude видел только нужные tools. |
Custom connectors для Claude.ai или Claude Desktop - отдельный user-facing route. Они тоже используют remote MCP, но product surface, approvals, admin controls, plan availability и network requirements отличаются от backend Messages API integration. Anthropic cloud infrastructure должен reach your connector, поэтому "у нас это работает в private network" не является достаточным production design.
Для внутреннего API network boundary решает, где запускается MCP server, какие firewall rules существуют, как выдаются OAuth или service tokens, как enforced tenant boundaries и кто утверждает tool access. Connector, который читает или меняет internal systems, должен проходить такой же security review, как любой внешний integration endpoint.
| Вопрос | Direct tools | API MCP connector | Custom connector |
|---|---|---|---|
| Кто обращается к internal system? | Ваш app backend | Remote MCP server reachable by Claude API path | Remote MCP server reachable by Claude user surface |
| Где enforced auth? | App session, tenant policy, service account | MCP server, connector config, headers, internal policy | User/admin approval, connector auth, MCP server, internal policy |
| Хороший first use | Product-owned workflow | Shared internal toolset for Messages API | Human Claude workflow with approved remote tools |
| Первый риск | Hidden broad execution inside app code | Exposing too many tools or too much data | User permissions, write actions, prompt injection |
Remote MCP server проектируйте как production service: health checks, auth verification, request logs, rate limits, schema tests, typed errors, result-size limits и safe failure responses. Если server нужен только для одного developer laptop, оставьте его в Claude Code branch.
Claude Code и Desktop - локальная ветка workflow
Claude Code MCP хорошо подходит для local developer workflows: repo tools, scripts, internal docs search, issue trackers, read-only database helpers, browser verification и team-specific utilities. Local stdio, project scope, user scope и /mcp commands относятся именно сюда.
Но Claude Code settings не определяют production app tool surface. Если ваше приложение вызывает Messages API, .mcp.json на ноутбуке разработчика не становится API connector. Если stdio server работает локально, это доказывает local workflow branch, а не remote reachability.
Локальная проверка может выглядеть так:
bashclaude mcp add --scope project support-search --transport stdio -- ./scripts/support-search-mcp claude mcp list
Remote path должен проверяться как deployed service:
bashclaude mcp add --scope project support-search https://mcp.example.com/mcp
Разделяйте эти branches в docs и runbooks. Local stdio может читать local file system, запускать local commands и использовать developer-specific credentials. Remote HTTP server требует deployment, TLS, auth, observability и stable interface. Смешивание assumptions часто дает demo, которое невозможно утвердить для production.
Если вопрос в выборе MCP servers для Claude Code, используйте лучшие Claude Code MCP servers. Если setup уже стал слишком широким, идите в Claude Code MCP context overload. Если проблема в credentials, provider route или base URL, используйте Claude Code API configuration.
Production Safety Checklist
Внутренние tools должны проходить safety ladder. Первая версия доказывает, что Claude может читать bounded data и возвращать useful summaries. Write access появляется только после preview, approval, audit и verification.
| Gate | Pass condition | Stop if... |
|---|---|---|
| Tool scope | Каждый tool соответствует одному outcome и одной narrow operation | Tool принимает arbitrary endpoint, SQL, shell или mutation |
| Credential scope | Credentials server-side, least privilege, separated by environment | Claude видит secrets или использует broad admin credentials |
| Read-only proof | Reads return compact results with source ids | Reads return raw dumps, secrets или unlimited rows |
| Write preview | Writes create drafts or previews first | Write executes immediately without approval |
| Approval path | Risky actions record approver, reason и audit id | Approval exists only in prompt text |
| Audit log | Every call records actor, user, tool, input summary, output summary, result id | Нельзя восстановить, что Claude пытался сделать |
| Output budget | Limits, pagination, summaries и handles by default | Single call floods context with logs, rows или documents |
| Prompt guard | Tool results treated as untrusted data | Retrieved content can instruct Claude to bypass policy |
Approval design должен соответствовать риску. Billing summary может требовать только auth и logging. Refund, deployment, permission change, account suspension или database mutation требует preview, approval record и final state check. Если rollback unavailable, это должно быть visible до approval.
Audit log важен не только для compliance. Он нужен для debugging: какой tool выбрала модель, какие параметры передала, почему permission check прошел или отказал, какой result size вернулся, как Claude интерпретировал response. Без этого "tool integration is unstable" будет guess, а не diagnosis.
Implementation Sketch
Pattern одинаковый для direct tools и MCP: define narrow tool, execute in trusted code, return compact output, log attempt. Разница в том, где живет contract и кто вызывает handler.
Для direct Claude API tools app 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 compact tool_result and write audit entry.
Для remote MCP server API team владеет server contract. Server exposes tool definitions and handlers; Claude clients connect through the chosen product surface. Первая версия должна быть boring:
| Server design choice | Better default |
|---|---|
| Tool naming | Verb plus domain outcome, например get_customer_billing_summary |
| Input schema | Required ids, reason, time windows, limits, enum values |
| Output schema | Summary fields, source ids, next action, warnings, cursor |
| Error handling | Typed domain errors instead of raw stack traces |
| Observability | Tool call id, actor id, request id, latency, result size, policy decision |
| Permissions | Read-only by default; write tools behind explicit approval |
Если используете API MCP connector, expose only the small toolset needed for the task. Если используете custom connectors, review user consent and admin controls. Если используете Claude Code, храните config в правильном scope и не commit secrets. Один и тот же internal tool может потом поддерживать несколько surfaces, но first production version должна доказать один route cleanly.
Best Next Move
Следующий шаг зависит от execution owner:
| Ситуация | Следующий шаг |
|---|---|
| Один app needs a few internal reads | Implement direct Claude API tools with compact tool_result and audit log. |
| Несколько Claude clients need same internal toolset | Design custom MCP server with read-only tools first, then connect through API MCP connector or approved surface. |
| Work is local developer automation | Keep it in Claude Code MCP, choose scope deliberately, monitor context load. |
| Human Claude.ai/Desktop workflow needs approved tools | Use custom connector plan, approval model and network design, not local stdio assumptions. |
| Hard problem is hosted long-running runtime | Compare with Claude Managed Agents before building your own loop. |
Самый надежный first milestone - read-only end-to-end proof: model request, tool selection, auth check, internal API call, compact result, audit log и human-visible answer. После этого добавляйте allowlists, output caps, approvals и write previews. Только потом решайте, заслуживает ли contract отдельного MCP server.
Часто задаваемые вопросы
Нужно ли использовать MCP, чтобы подключить Claude к внутренним API?
Нет. Direct Claude API tools часто достаточно, если один app владеет loop и может сам execute tool calls. MCP нужен, когда один tool contract должен переиспользоваться across clients или connector surfaces.
Чем direct Claude API tools отличаются от Claude API MCP connector?
В direct tools ваше приложение получает tool_use, выполняет internal operation и возвращает tool_result. В API MCP connector Messages API подключает Claude к remote MCP server, который владеет interface. Connector route добавляет server и network boundary, поэтому сложность должна окупаться reuse.
Может ли API MCP connector использовать local stdio MCP server?
Не напрямую. На 1 июня 2026 года API connector требует remote HTTP/SSE MCP server. Local stdio относится к Claude Code или локальным Desktop-style workflows.
Можно ли открыть весь внутренний API как MCP tools?
Нет. Открывайте task-shaped tools с narrow schemas и compact outputs. Broad endpoint caller, arbitrary SQL, shell или admin mutation слишком рискованны и плохо reviewable.
Как должны работать write actions?
Начинайте с read-only tools. Для writes сначала делайте draft или preview, затем approval с reason, actor, idempotency key, audit id и final verification. High-risk actions не должны execute только потому, что prompt попросил.
Влияют ли MCP tool results на context size?
Да. Tool definitions, calls и results добавляют context. Возвращайте summaries, filtered results, pagination и source ids. Если Claude не нужен raw payload, возвращайте handle or record id.
Где здесь Claude Code MCP?
Claude Code MCP подходит для local developer workflows: project tools, scripts, repo helpers, local automation. Он не заменяет deployed Messages API connector with network, auth и audit.
Что проверить перед production?
Проверьте route owner, server reachability, beta headers or connector requirements, auth scope, tool allowlist, read-only result shape, write approval, audit logging, output limits и prompt-injection handling. Если что-то unclear, оставьте integration in read-only pilot.