AI SDK + MCP: una guía práctica de integración para sistemas de agentes en producción

Puntos clave

• Integrar AI SDK + MCP no es solo "conectar y llamar". El trabajo real está en el alcance, el transporte, los reintentos, la autenticación y la observabilidad.
• El punto de partida más seguro es discovery estrecha, allowlists explícitas de herramientas y presupuestos duros por solicitud.
• MCP mejora discovery e invocation, pero la aplicación sigue teniendo que decidir qué herramientas exponer en cada workflow.
• Un sistema de agentes en producción necesita decisiones previas sobre timeouts, fallback y logging.
• puppyone encaja bien cuando el mismo workflow necesita contexto gobernado y herramientas servidas por MCP.

Por qué en demo parece fácil y en producción no tanto

El flujo demo siempre se ve igual:

1. conectar el AI SDK a un servidor MCP
2. exponer algunas herramientas
3. dejar que el modelo las llame

Eso sirve para un prototipo. No basta para producción.

En producción aparecen nuevas decisiones:

• ¿Qué herramientas puede ver este agente?
• ¿Qué transporte es aceptable en este entorno?
• ¿Cómo se rotan las credenciales?
• ¿Qué pasa si el servidor MCP responde lento?
• ¿Cuál es el fallback si falla la llamada?
• ¿Qué acciones requieren aprobación humana?
• ¿Cómo se explica una ejecución después de un error?

La arquitectura mínima que de verdad importa

user request
  -> runtime del agente en tu app
  -> política de herramientas por workflow
  -> cliente MCP
  -> uno o más servidores MCP
  -> sistemas externos o contexto gobernado
  -> ensamblado del resultado
  -> logs, aprobaciones y trazas

La línea que muchos equipos omiten es la política de herramientas.

Discovery es una capacidad del protocolo. Exposure es una decisión de producto.

Las cinco decisiones que más pesan

1. Discovery no es permiso

Que el SDK descubra veinte herramientas no significa que el workflow deba ver veinte herramientas.

Trata discovery como el conjunto máximo y la allowlist de runtime como el límite real de ejecución.

2. El transporte es una decisión de fiabilidad

La documentación actual de AI SDK recomienda HTTP para despliegues productivos y deja stdio para servidores locales. Eso cambia firewalls, reintentos, proxying y ownership operativo.

La regla correcta suele ser la aburrida:

• usa el transporte más simple que tu entorno pueda operar bien
• mantén reintentos acotados
• define explícitamente el comportamiento ante timeout

3. Las descripciones de herramientas cambian el comportamiento del modelo

Descripciones vagas generan uso vago. Si dos herramientas se solapan, el modelo gasta tokens eligiendo entre opciones confusas.

Describe cada herramienta como lo haría un operador prudente:

• qué hace
• qué no hace
• cuándo debe usarse
• qué entradas exige
• cómo falla

4. Cada llamada necesita presupuesto

El modelo no debería poder:

• llamar diez herramientas si dos bastan
• reintentar sin límite
• traer payloads gigantes al prompt
• mezclar herramientas de solo lectura y de escritura sin control

5. Los logs son parte de la feature

Necesitas algo más que "el modelo decidió mal". Como mínimo:

• request ID
• herramientas expuestas
• herramienta elegida
• argumentos enviados
• latencia y fallos
• estado de aprobación

Una tabla que evita muchos errores

La regla útil suele ser:

• discovery amplia para explorar
• bundles explícitos por workflow para producción

Dónde encaja puppyone

Cuando el sistema necesita contexto gobernado y tool calling, puppyone ocupa una posición útil:

• preparar el contexto una sola vez de forma estructurada
• exponerlo por MCP o API
• dejar visible solo la capacidad que cada workflow necesita
• mantener el camino de decisión inspeccionable

Un rollout sensato

Despliega AI SDK + MCP en este orden:

1. un workflow de solo lectura
2. un servidor MCP
3. una allowlist explícita
4. un presupuesto de latencia
5. un camino de logging

Después añade:

• acciones de escritura
• aprobaciones
• fallback
• routing multi-servidor
• bundles por rol

FAQs

Q1: ¿MCP reemplaza a las herramientas nativas del SDK?

No. MCP ofrece una forma estándar de descubrir y usar capacidades externas. Las herramientas nativas de la app pueden seguir existiendo.

Q2: ¿Toda integración con AI SDK debería exponer todas las herramientas MCP descubiertas?

No. Discovery debe convertirse en una allowlist más estrecha en runtime. Exponer el catálogo completo suele empeorar la fiabilidad.

Q3: ¿Cuál es la primera señal de producción que conviene monitorear?

Empieza por calidad de selección de herramientas y latencia. Si el modelo elige mal o tarda demasiado en tool calls, la calidad percibida cae rápido.