Claude puede usar una API interna por más de una ruta. MCP es útil cuando necesitas un contrato de herramientas reutilizable, pero no reemplaza el diseño de API, la autorización, las aprobaciones ni los logs de auditoría.
La primera decisión no es "¿cómo instalo MCP?", sino quién será dueño de la ejecución. Si tu aplicación ya controla el prompt, el estado, la sesión del usuario, la ejecución de tools y la auditoría, direct Claude API tools suele ser el camino más corto. Si varias superficies de Claude necesitan el mismo conjunto de herramientas internas, conviene diseñar un remote MCP server estrecho y exponer solo las operaciones que Claude realmente necesita.
A 1 de junio de 2026, la documentación de Anthropic separa direct tool use, Messages API MCP connector, Claude Code MCP y Claude custom connectors. Trátalos como rutas distintas:
| Si tu integración necesita... | Empieza por... | Por qué |
|---|---|---|
| Una app controla prompts, estado, ejecución y auditoría | Direct Claude API tools | La app recibe tool_use, ejecuta la operación interna y devuelve tool_result dentro de su propio límite de auth. |
| Messages API debe llamar un toolset remoto reutilizable | Claude API MCP connector | Conecta Claude con un remote MCP server alcanzable sin montar un MCP client separado dentro de tu app. |
| Varias superficies de Claude deben compartir el mismo contrato interno | Custom MCP server | El equipo de API mantiene una interfaz acotada en vez de adaptadores por cliente. |
| Un desarrollador necesita acceso local al repo, archivos o comandos | Claude Code MCP | Local stdio, project scope y controles /mcp pertenecen al workflow local de desarrollo. |
| Un flujo humano en Claude.ai o Desktop necesita un connector aprobado | Custom connector | Es una ruta user-facing con límites propios de plan, permisos, red y administración. |
| El problema real es un agente hosted de larga duración | Managed Agents | Úsalo solo cuando el runtime hosted sea el problema, no solo el acceso a herramientas. |
Regla de parada: no construyas un MCP server solo porque MCP está disponible. Hazlo cuando reutilización, ownership del connector o consistencia entre clientes valgan el coste extra de server, auth, review y observabilidad.
Tools directas de Claude API vs MCP
La ruta más corta suele ser Claude API tool use. Tu aplicación envía definiciones de tools, Claude puede devolver un bloque tool_use, tu código ejecuta la operación interna y luego devuelve tool_result. Eso basta cuando una app posee el prompt, la sesión de usuario, los chequeos de autorización, la ejecución, los retries, el audit log y la forma final de la respuesta.
MCP aporta valor cuando el contrato de tool debe sobrevivir a una sola app. Si el equipo de API quiere que la misma búsqueda interna, ticket, billing, deployment o reporting tool funcione en varias superficies de Claude, un custom MCP server puede ser la abstracción correcta. El server se convierte en la interfaz acotada. Los clientes de Claude consumen tools; el equipo de API controla nombres, schemas, auth, límites de salida y policy.
| Decisión | Usa direct Claude API tools | Construye o expón MCP |
|---|---|---|
| Dueño del runtime | Una aplicación ya ejecuta el loop | Varios clientes necesitan el mismo contrato de tools |
| Ejecución | Tu app ejecuta la llamada y devuelve tool_result | Un server remoto debe ejecutar detrás de un límite de protocolo |
| Auth boundary | La sesión de la app y una service account son suficientes | Importan connector-level auth, headers, allowlists o ownership por tool |
| Control de cambios | Un equipo de producto puede actualizar la integración | API/platform necesita un contrato estable para varias superficies |
| Coste operativo | Mantén la primera versión pequeña | Acepta server, despliegue, revisión y monitoring adicionales |
El umbral práctico es reutilización más ownership. Si la tool solo se usa dentro de un workflow de producto, direct tools suele ser más claro. Si la misma operación debe estar disponible para llamadas Claude API, connectors de Claude.ai, proyectos Claude Code o agentes internos futuros, MCP puede justificar las piezas extra.
No definas MCP tools como copias finas de endpoints backend. Claude no necesita todo tu admin API. Necesita capacidades con forma de tarea, como search_customer_ticket, summarize_invoice_status, create_refund_draft u open_deployment_incident. Esos nombres no son cosméticos. El nombre, la descripción, el schema y el contenido devuelto forman parte de la interfaz sobre la que Claude razona, igual que describe la MCP tool specification.
Diseña un wrapper estrecho para la API interna
Una integración segura de Claude con herramientas internas empieza con una capa wrapper. El wrapper traduce una API interna existente a un contrato de tool pequeño, con inputs explícitos, outputs acotados, credenciales limitadas y fallos previsibles. El objetivo no es ocultar complejidad a los ingenieros. El objetivo es darle a Claude una superficie de acción suficientemente útil para completar la tarea y suficientemente estrecha para poder revisarla.
Empieza por el resultado de usuario y retrocede hasta la tool mínima:
| Resultado | Mala forma de tool | Mejor forma de tool |
|---|---|---|
| Revisar estado de billing de un cliente | call_internal_billing_api con path y body arbitrarios | get_customer_billing_summary con customer_id, estado, última factura y siguiente acción |
| Preparar un refund | admin_mutation con JSON libre | create_refund_draft que devuelve un draft id y exige aprobación humana antes de ejecutar |
| Investigar un incidente | query_logs con texto y rango sin límites | summarize_incident_errors con service, time window, limit, count y sample lines |
| Añadir una nota CRM | write_crm con acceso libre a endpoint | append_account_note con account id, note text, reason, actor y audit id |
El wrapper también debe decidir qué no recibe Claude. Mantén secretos en el servidor. No devuelvas tokens, raw PII, filas completas de base de datos ni logs sin límite salvo que el workflow lo requiera de verdad y la política lo permita. Si Claude solo necesita tomar una decisión, devuelve un resumen listo para decidir con source ids, counts, timestamps y una muestra pequeña.
Diseña resultados compactos desde el principio. No es solo una cuestión de coste de tokens. Payloads grandes de APIs internas hacen que Claude inspeccione campos ruidosos, filas irrelevantes y metadatos repetidos. Un mejor resultado es corto, tipado y orientado a acción:
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"] }
El wrapper debe hacer que las acciones peligrosas sean más lentas que las lecturas seguras. Un resumen read-only puede responder de inmediato. Una escritura normalmente debería crear un draft, exigir aprobación y registrar quién aprobó. La tool debe tener campo de reason, idempotency key, preview response y una ruta de rollback o cancelación cuando el dominio la soporte.
Límites remotos: API MCP Connector, Custom Connectors y alcance de red
El Claude API MCP connector no es lo mismo que un Claude Code MCP server local. Permite que Messages API conecte Claude directamente con remote MCP servers, pero el server debe ser alcanzable por HTTP con Streamable HTTP o SSE. Los servidores stdio locales no se conectan directamente por esta ruta de API.
A 1 de junio de 2026, estos límites de implementación deben quedar cerca de cualquier plan de producción:
| Límite | Consecuencia de planificación actual |
|---|---|
| Beta header | Las requests requieren actualmente anthropic-beta: mcp-client-2025-11-20; nombres de header antiguos deben tratarse como stale hasta volver a verificarlos. |
| Transporte | Usa un remote HTTP/SSE MCP server alcanzable para el API connector. No pegues un comando local stdio de Claude Code en esta ruta. |
| Alcance de capacidad | El connector soporta actualmente llamadas a MCP tools, no un túnel general para cualquier primitiva MCP. |
| Retención de datos | La documentación de Anthropic dice que el MCP connector no está cubierto por ZDR, así que las tools sensibles necesitan revisión explícita. |
| Control de tools | Usa allowlists, denylists y controles de connector para que el modelo vea solo las tools necesarias para la tarea. |
Los custom connectors para Claude.ai o Claude Desktop son otra ruta user-facing. También usan remote MCP, pero la superficie de producto, el modelo de aprobación, la disponibilidad por plan y los controles admin son distintos de una integración backend con Messages API. La infraestructura cloud de Anthropic debe poder alcanzar el connector, así que las suposiciones de red privada deben probarse antes de aceptar el diseño.
Para APIs internas, ese hecho de red no es un detalle menor de despliegue. Decide dónde corre el MCP server, qué reglas de firewall existen, cómo se emiten OAuth o service tokens, cómo se aplican límites de tenant y quién puede aprobar acceso a tools. Un connector que llega a un sistema interno sensible necesita la misma revisión de seguridad que cualquier integración externa capaz de leer o mutar datos de la empresa.
Usa esta tabla antes de escribir código:
| Pregunta | Direct tools | API MCP connector | Custom connector |
|---|---|---|---|
| ¿Quién alcanza el sistema interno? | Backend de tu aplicación | Remote MCP server alcanzable por la ruta Claude API | Remote MCP server alcanzable por la superficie de usuario Claude |
| ¿Dónde se aplica auth? | Sesión de app, service account y tool executor | MCP server, connector config, headers y política interna | Connector auth, aprobación user/admin, MCP server y política interna |
| Buen primer uso | Workflow owned by product | Toolset interno compartido para Messages API | Workflow humano Claude con remote tools aprobadas |
| Primer riesgo de producción | Ejecución amplia escondida dentro del código de app | Exponer demasiadas tools o devolver demasiados datos | Permisos user-facing, write actions y prompt-injection risk |
Si el MCP server es remoto, diséñalo como una integración de producción, no como un script cómodo para demos. Agrega health checks, request logging, auth verification, rate limits, schema tests y safe failure responses. Si el server es solo una ayuda local para un desarrollador, mantenlo en la rama Claude Code en vez de promoverlo a API connector.
Claude Code y Desktop son la rama local
Claude Code MCP encaja muy bien en workflows locales de desarrollo: tools de repositorio, scripts del proyecto, docs internas, issue trackers, helpers de lectura de base de datos, browser verification o utilidades específicas del equipo. También es la rama donde tiene sentido local stdio. La documentación actual de Claude Code MCP y la ayuda CLI separan local, project y user scopes, y la sintaxis actual soporta transports stdio, sse y http.
Eso no convierte a Claude Code en el runtime para toda integración de herramientas internas. Si tu app de producción llama Messages API, los settings de Claude Code en el laptop de un desarrollador no definen la superficie de tools de la app. Que un server local stdio funcione en Claude Code solo prueba la rama local. No prueba que un remote API connector pueda alcanzar la misma tool.
Usa Claude Code MCP cuando el trabajo sea local:
bashclaude mcp add --scope project support-search --transport stdio -- ./scripts/support-search-mcp claude mcp list
Usa una ruta remota cuando el trabajo sea backend o cross-client:
bashclaude mcp add --scope project support-search https://mcp.example.com/mcp
Documenta las dos ramas por separado. Un MCP server local puede leer el filesystem local, llamar comandos locales o depender de credenciales propias del desarrollador. Un remote MCP server requiere deployment, networking alcanzable, auth, observabilidad y una interfaz pública más estricta. Mezclar esas suposiciones es la forma típica de construir algo que funciona en una demo pero no pasa aprobación de producción.
Si la decisión real es qué MCP servers convienen en Claude Code, usa la guía workflow-first de Claude Code best MCP servers. Si el problema es exceso de servers activos o resultados que llenan el contexto, usa la ruta de limpieza de Claude Code MCP context overload. Si la confusión viene de credenciales, variables de entorno o base URLs de provider, revisa primero Claude Code API configuration.
Checklist de seguridad para producción
Las herramientas internas deben avanzar por una escalera de seguridad. La primera versión debería probar que Claude puede leer datos acotados y devolver resúmenes útiles. El acceso de escritura llega después, cuando preview, approval, audit y rollback sean lo bastante aburridos para confiar.
| Gate | Condición de pass | Stop if... |
|---|---|---|
| Tool scope | Cada tool mapea a un user outcome y una operación interna estrecha | La tool acepta endpoint, SQL, shell o mutation input arbitrario |
| Credential scope | Credenciales server-side, least-privilege y separadas por entorno | Claude puede ver secretos o reutilizar credenciales admin amplias |
| Read-only proof | Lecturas devuelven resultados compactos, listos para decidir, con source ids | Lecturas devuelven dumps crudos, secretos o sets sin límite |
| Write preview | Write tools crean drafts o previews antes de ejecutar | Una escritura se ejecuta sin aprobación humana o de policy |
| Approval path | Acciones riesgosas requieren approver, reason y durable audit id | La aprobación existe solo en el texto del prompt |
| Audit log | Cada tool call registra actor, user, tool, input summary, output summary y result id | No puedes reconstruir qué intentó Claude y qué cambió realmente |
| Output budget | Resultados tienen limits, pagination, summaries y file handles para datos profundos | Una llamada puede inundar el contexto con logs, filas o documentos completos |
| Prompt-injection guard | Tool results se tratan como datos no confiables, sobre todo tickets, docs, webs y user content | El output de una tool puede instruir a Claude a saltarse policy o llamar write tools |
Trata prompt injection como un problema de herramientas internas, no solo de navegación web. Support tickets, notas CRM, docs, emails, Slack exports, comentarios de base de datos y archivos subidos por clientes pueden contener instrucciones adversarias. El wrapper debe etiquetar contenido recuperado como datos, separarlo de system policy y evitar texto crudo innecesario cuando basta un structured summary.
El diseño de aprobación debe coincidir con la acción. Resúmenes read-only de bajo riesgo quizá solo necesiten auth normal y logging. Un refund, deployment, permission change, account suspension o database mutation necesita preview, approval record y una forma de verificar el estado final. Si el dominio no ofrece rollback, la tool debe decirlo antes de la aprobación.
Boceto de implementación
El patrón es el mismo si empiezas con direct tools o MCP: define una tool estrecha, ejecútala en código confiable, devuelve output compacto y registra el intento. La diferencia es dónde vive el contrato de tool y qué runtime lo llama.
Para direct Claude API tools, el loop de la aplicación posee la ejecución:
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.
Para un remote MCP server, el equipo de API posee el contrato del server. El server expone tool definitions y handlers; los clientes de Claude se conectan por la superficie elegida. Mantén aburrido el primer server:
| Decisión de diseño | Mejor default |
|---|---|
| Naming | Verb plus domain outcome, por ejemplo get_customer_billing_summary |
| Input schema | Required ids, reason fields, time windows, limits y enum values |
| Output schema | Summary fields, source ids, next action, warnings y cursor |
| Error handling | Typed domain errors en vez de raw stack traces |
| Observability | Tool call id, actor id, request id, latency, result size y policy decision |
| Permissions | Read-only por defecto; write tools detrás de aprobación explícita |
Si usas Claude API MCP connector, solicita un conjunto pequeño de tools en vez de exponer todo lo que el server sabe hacer. Si usas custom connectors, revisa consent user-facing y admin controls. Si usas Claude Code, guarda el setup local en el scope correcto y no comitees secretos. La misma tool interna puede terminar soportando varias superficies, pero la primera versión de producción debería demostrar una ruta limpia antes de abrir más ramas.
Mejor siguiente paso
El siguiente movimiento depende de qué ruta posee la ejecución:
| Situación actual | Siguiente paso |
|---|---|
| Una app controla el workflow y solo necesita algunas lecturas internas | Implementa direct Claude API tools con payloads tool_result compactos y audit logs. |
| Varios clientes Claude necesitan el mismo toolset interno | Diseña un custom MCP server con read-only tools primero y conéctalo por API MCP connector u otra superficie aprobada. |
| El trabajo es automatización local de desarrollo | Mantenlo en Claude Code MCP, elige project/user scope con intención y controla context load. |
| El trabajo es un flujo humano en Claude.ai o Desktop | Usa custom connector plan, approval model y network design, no supuestos de local stdio. |
| El problema duro es runtime hosted de larga duración | Compara la ruta con Claude Managed Agents antes de construir tu propio loop. |
El hito más confiable es una tool read-only que demuestre todo el camino: model request, tool selection, auth check, llamada a la API interna, resultado compacto, audit log y respuesta visible para un humano. Después agrega allowlists, output caps, approval flows y write previews. Solo entonces decide si el mismo contrato merece convertirse en un MCP server reutilizable.
Preguntas frecuentes
¿MCP es obligatorio para conectar Claude con APIs internas?
No. Direct Claude API tools suele ser suficiente cuando una aplicación posee el loop y puede ejecutar tool calls por sí misma. MCP es útil cuando necesitas un contrato reutilizable en varios clientes de Claude o superficies de connector.
¿Cuál es la diferencia entre direct Claude API tools y Claude API MCP connector?
Con direct tools, tu aplicación recibe tool_use, ejecuta la operación interna y devuelve tool_result. Con Claude API MCP connector, Messages API conecta Claude con un remote MCP server que posee la interfaz de tools. La ruta connector añade server y network boundary, así que debe ganarse esa complejidad.
¿Claude API MCP connector puede usar un MCP server local stdio?
No directamente. A 1 de junio de 2026, la documentación del API connector de Anthropic requiere un remote HTTP/SSE MCP server. Local stdio pertenece a Claude Code o workflows locales tipo Desktop, no a la ruta Messages API connector.
¿Debería exponer toda mi API interna como MCP tools?
No. Expón tools con forma de tarea, schemas estrechos y outputs compactos. Callers de endpoints amplios, SQL arbitrario, shell tools o admin mutation tools son difíciles de usar con seguridad y difíciles de revisar.
¿Cómo deberían funcionar las acciones de escritura?
Empieza con read-only tools. Para escrituras, prefiere drafts o previews primero, luego aprobación con reason, actor, idempotency key, audit id y verification path. Acciones de alto riesgo no deberían ejecutarse solo porque un prompt lo pidió.
¿Los MCP tool results afectan el tamaño de contexto?
Sí. Tool definitions, tool calls y tool results pueden sumar contexto. Mantén outputs cortos, resumidos, filtrados y paginados. Devuelve handles o source ids cuando Claude no necesita todo el payload crudo.
¿Dónde encaja Claude Code MCP?
Claude Code MCP encaja en workflows locales de desarrollo. Úsalo para project-scoped tools, scripts locales, repo helpers y automatización de desarrollo. No trates un setup local de Claude Code MCP como prueba de que un backend Messages API connector está desplegado o alcanzable.
¿Qué debo verificar antes de producción?
Verifica route owner, reachability del server, beta headers o requisitos del connector, auth scope, tool allowlist, read-only result shape, write approval flow, audit logging, output limits y prompt-injection handling. Si algo de eso no está claro, mantén la integración como piloto read-only.