AI SDK + MCP: um guia prático de integração para sistemas de agentes em produção

Principais pontos

• Integrar AI SDK + MCP não é só "conectar e chamar". O trabalho real está em escopo, transporte, retries, autenticação e observabilidade.
• O ponto de partida mais seguro é discovery estreita, allowlists explícitas de ferramentas e budgets rígidos por requisição.
• MCP melhora discovery e invocation, mas a aplicação continua responsável por decidir quais ferramentas cada workflow deve enxergar.
• Um sistema de agentes em produção precisa de decisões explícitas sobre timeout, fallback e logging antes do primeiro incidente.
• puppyone é especialmente útil quando o mesmo workflow precisa de contexto governado e ferramentas entregues via MCP.

Por que parece fácil em demos e mais difícil em produção

O fluxo de demo sempre parece simples:

1. conectar o AI SDK a um servidor MCP
2. expor algumas ferramentas
3. deixar o modelo chamá-las

Isso é suficiente para um protótipo. Não é suficiente para produção.

Em produção, aumentam as decisões que você precisa assumir:

• quais ferramentas esse agente pode ver?
• qual transporte é aceitável neste ambiente?
• como autenticar e girar credenciais?
• o que acontece quando o servidor MCP fica lento?
• qual é o fallback quando a chamada falha?
• quais chamadas precisam de aprovação humana?
• como explicar uma execução depois que algo deu errado?

A arquitetura mínima que importa

user request
  -> agent runtime no seu app
  -> política de ferramentas por workflow
  -> cliente MCP
  -> um ou mais servidores MCP
  -> sistemas externos ou contexto governado
  -> montagem do resultado
  -> logs, aprovações e traces

A linha que muitas equipes pulam é a política de ferramentas.

Discovery é uma função do protocolo. Exposure é uma decisão de produto.

As cinco decisões mais importantes

1. Discovery não é permission

Só porque o SDK descobre vinte ferramentas não significa que o workflow deva ver vinte ferramentas.

Discovery deve ser tratada como conjunto máximo, e a allowlist de runtime como a fronteira real de execução.

2. Transporte é uma escolha de confiabilidade

A documentação atual do AI SDK recomenda HTTP para produção e deixa stdio mais para servidores locais. Isso muda firewall, retries, proxying e ownership operacional.

A regra certa costuma ser a mais simples:

• usar o transporte mais simples que o ambiente consiga operar bem
• limitar retries
• deixar o comportamento de timeout explícito

3. A descrição da ferramenta muda o comportamento do modelo

Descrições vagas geram uso vago. Se duas ferramentas se sobrepõem, o modelo gasta tokens escolhendo em vez de resolver.

Descreva a ferramenta como um operador cauteloso faria:

• o que ela faz
• o que ela não faz
• quando deve ser usada
• quais entradas exige
• como falha

4. Toda chamada precisa de budget

O modelo não deveria poder:

• chamar dez ferramentas quando duas bastam
• repetir para sempre
• puxar payloads gigantes para o prompt
• misturar ferramentas de leitura e escrita sem controle

5. Logs fazem parte da funcionalidade

Não basta dizer "o modelo decidiu mal". Você precisa de:

• request ID
• ferramentas expostas no run
• ferramenta realmente escolhida
• argumentos enviados
• latência e falhas
• estado de aprovação quando houver

Uma tabela que evita muitos erros

A regra prática costuma ser:

• discovery ampla para explorar
• bundles explícitos por workflow para produção

Onde puppyone entra

Quando o sistema precisa de contexto governado e tool calling ao mesmo tempo, puppyone ocupa uma posição útil:

• preparar contexto estruturado uma vez
• expor esse contexto por MCP ou API
• mostrar apenas as capacidades que o workflow deve ver
• manter o caminho de decisão auditável

Uma sequência de rollout mais segura

Implante AI SDK + MCP nesta ordem:

1. um workflow somente leitura
2. um servidor MCP
3. uma allowlist explícita
4. um budget de latência
5. um caminho de logging

Depois adicione:

• ações de escrita
• aprovações
• fallback
• roteamento multi-servidor
• bundles por função

FAQs

Q1: MCP substitui ferramentas nativas do SDK?

Não. MCP oferece uma forma padrão de descobrir e usar capacidades externas. As ferramentas nativas do app continuam podendo coexistir.

Q2: Toda integração com AI SDK deve expor todas as ferramentas MCP descobertas?

Não. Discovery deve virar uma allowlist de runtime mais estreita. Expor o catálogo inteiro costuma prejudicar a confiabilidade.

Q3: Qual sinal de produção monitorar primeiro?

Comece por qualidade de seleção de ferramentas e latência. Se o modelo escolhe errado ou demora demais nos tool calls, a qualidade para o usuário cai rapidamente.