Módulo 2.5 — Tools customizadas, MCP e grep/glob | DeerFlow 2.0

💡 Onde este módulo se encaixa

Você já sabe middleware (2.2), skill (2.3) e custom agent (2.4). Faltava a última peça: tools reais — o que cruza a fronteira do processo e fala com o mundo. É aqui que o agente deixa de ser um loop de texto e começa a fazer coisas.

📄 RFC rfc-grep-glob-tools

A RFC rfc-grep-glob-tools propõe dois primitivos nativos — grep e glob — como tools de primeira classe no harness. Parece trivial mas resolve um problema recorrente: agentes que gastam tokens inteiros listando diretórios ou lendo arquivos grandes para achar uma string.

Motivação

Agentes gastavam 2-5k tokens por sessão só descobrindo o layout do repositório. A solução ad-hoc era colocar shell como tool, mas isso abre mão de sandbox. A RFC defende dois primitivos explícitos, dedicados, sandbox-friendly.

grep tool

Args: pattern, path, glob, output_mode. Usa ripgrep no backend, devolve só os matches (nome do arquivo + linha). Nunca lê arquivos inteiros.

glob tool

Args: pattern. Devolve lista de paths ordenada por data de modificação. Substitui "list directory" que o modelo insistia em inventar quando não havia tool própria.

Integração com sandbox

Ambas rodam read-only dentro do sandbox configurado. Sem acesso a /etc, sem gravação, sem execução. Auditado por middleware como qualquer tool.

🌐 Expor serviço como MCP server

MCP (Model Context Protocol) é o padrão da Anthropic que o DeerFlow adota como transporte preferencial para tools externas. Expor uma API interna como MCP server significa que qualquer harness compatível (DeerFlow, Claude Desktop, Cursor) pode consumir essas tools sem código específico.

🎯 Conceito Central

Um MCP server declara: (a) um contrato com lista de tools + schemas JSON, (b) um transport (stdio para local, HTTP/SSE para remoto), (c) um handler por tool que recebe args e devolve resultado. O cliente (harness) descobre as tools por introspecção, sem hardcoding.

•stdio — subprocess local, sem rede. Ideal para dev, CLI, tools de filesystem.
•HTTP + SSE — serviço remoto, autenticado, disponível em rede. Ideal para APIs internas da empresa.
•Schema auto-descoberto — o harness chama tools/list na hora do boot e registra tudo.
•Versionamento — bump do servidor = bump da lista. Clientes reagem em reload.

💡 Por que MCP e não REST direto

Você poderia abrir uma tool que faz requests.get(...) em qualquer endpoint. Funciona — até a terceira integração. O que MCP entrega é descobrimento automático, schema consistente, autenticação padronizada e portabilidade entre harnesses. O mesmo servidor que o DeerFlow consome serve Claude Desktop, Cursor e qualquer cliente MCP-compatível. Custo de escrever é o mesmo; economia na segunda integração já paga.

🔐 OAuth flows

MCP via HTTP/SSE em produção exige autenticação. O DeerFlow suporta dois fluxos OAuth padrão: client_credentials (server-to-server, sem usuário) e refresh_token (com usuário real, rotação). Saber qual usar evita surpresas em 30 dias.

📊 Dados dos fluxos

client_credentials — o harness troca client_id + client_secret por um access token de curta duração. Sem usuário. Uso: integrações internas, CI/CD, automações.
refresh_token — usuário final autoriza uma vez; harness guarda refresh token e troca por access tokens. Uso: Slack, Notion, Google, qualquer serviço com permissão por conta.
Escopo — sempre o menor possível. Uma tool que só lê não precisa de escopo write.
Rotação — refresh tokens em KMS/secret store; nunca em disco sem criptografia.
Expiração — monitorar e renovar com buffer (ex: 5 minutos antes de expirar).

Descoberta

Harness lê config/mcp.yaml e conecta ao servidor. Primeira chamada: initialize com auth token.

Lista de tools

Servidor retorna tools/list com nome, descrição e schema JSON de cada tool. Harness registra no catálogo runtime.

Invocação

Quando o agente decide usar, harness envia tools/call. Auth header injetado pelo middleware. Resultado volta serializado.

Renovação de token

Middleware detecta 401/token próximo a expirar, faz o refresh e retenta a call uma vez antes de propagar erro.

🚨 Alerta: credenciais nunca no prompt

Tokens vivem em variáveis de ambiente, secret stores ou KMS. O modelo nunca vê esses valores. O middleware injeta o header Authorization no handler, depois que a tool call já foi validada. Qualquer pipeline que coloque token no prompt é pipeline quebrado.

E não loge tokens no LangSmith. O DeerFlow tem redaction list padrão — mantenha atualizada sempre que adicionar novo campo sensível.

🧰 Tools customizadas além de MCP

Nem toda tool precisa virar MCP server. Para lógica que vive dentro da própria app, o DeerFlow aceita tools no formato LangChain — decorator @tool numa função Python com docstring clara, type hints e retorno serializável. É o caminho mais curto para adicionar capacidade nova.

💡 Quando usar cada formato

LangChain @tool local: lógica que só o DeerFlow usa, sem outros clientes, tem acesso ao state da app. Ex: enriquecer uma query com configs da empresa, parsear um formato proprietário.

MCP stdio: ferramenta de filesystem, CLI wrappers, scripts de manutenção. Isolamento de processo sai de graça.

MCP HTTP/SSE: API interna consumida por múltiplos agentes/clientes, com autenticação, rate limit, observabilidade do lado servidor. Padrão para produção.

Anatomia mínima de uma @tool

from langchain_core.tools import tool

@tool
def enrich_query_with_config(query: str, tenant_id: str) -> str:
    """Adiciona filtros específicos do tenant a uma query de busca.

    Use quando o usuário fizer uma pergunta de busca sem mencionar
    filtros e o tenant tiver restrições configuradas (ex: região,
    compliance, idioma).

    Args:
        query: a query original, em linguagem natural.
        tenant_id: identificador do tenant ativo.

    Returns:
        a query enriquecida, pronta para ser usada em search tools.
    """
    cfg = load_tenant_config(tenant_id)
    filters = " ".join(cfg.get("default_filters", []))
    return f"{query} {filters}".strip()

Docstring vira o schema — não pule nem abrevie. O modelo lê essa docstring para decidir se usa a tool.

🧪 Lab: API interna como MCP server

Expor uma API interna (fake mas realista) como MCP server, conectar ao DeerFlow e consultar via a skill brazilian-gov-research que você criou no módulo 2.3. No fim você tem: servidor MCP rodando, DeerFlow falando com ele, skill acionando as tools novas.

Passos do lab

1.
Criar API fake: um FastAPI mínimo em tools/internal-api/ com dois endpoints: GET /budget/<municipio>/<year> e GET /population/<municipio>. Dados mock num JSON.
2.
Envolver como MCP server: usar mcp SDK Python. Cada endpoint vira uma tool com schema JSON auto-gerado. Servidor expõe em http://localhost:8765/mcp usando SSE.
3.
Rodar servidor: uv run python -m internal_api.mcp_server. Teste com curl http://localhost:8765/mcp/tools — deve listar as duas tools.
4.
Configurar client no DeerFlow: em config/mcp.yaml, adicione um entry internal-api com transport http-sse, url do servidor, e OAuth client_credentials usando um client fake local.
5.
Reiniciar harness. No log de boot procure "mcp client connected: internal-api (2 tools)". Se der erro, 95% das vezes é OAuth — verifique client_id/secret.
6.
Ajustar a skill brazilian-gov-research: troque as tools fake pelas novas do MCP. Descrição e corpo permanecem — a ideia é que a skill aponte para tools que já existem no ambiente.
7.
Testar query completa: "qual o gasto de Florianópolis em saúde em 2024 por habitante?". No LangSmith, confirme que a skill foi acionada, chamou GET /budget/... e GET /population/..., e combinou os resultados.

💡 Entregável

Repositório (local) com: internal_api/ rodando, configuração MCP no DeerFlow, skill atualizada e trace do LangSmith mostrando as 2 chamadas à API interna. Bônus: rate limit de 10 req/s configurado no servidor para validar que o middleware trata 429 graciosamente.

📝 Resumo do Módulo

✓

grep e glob são primitivos sandbox-friendly — RFC rfc-grep-glob-tools mata a necessidade de expor shell.

✓

MCP é o transport padrão — contrato + schema + transport. Mesmo servidor serve DeerFlow e outros clients compatíveis.

✓

client_credentials para server-to-server, refresh_token para usuário — sempre escopo mínimo, nunca token no prompt.

✓

LangChain @tool é o atalho para tools locais — MCP só quando precisar de isolamento ou compartilhamento.

✓

API interna como MCP é composição — sobe o servidor, plugar no harness, ajustar a skill existente para usar as novas tools.

✓

Docstring da @tool é schema — escreva como se fosse documentação para humanos e para o modelo, que é o que é.

✓

Trilha 2 está encerrada — você agora consegue ler ARCHITECTURE, escrever middleware, criar skills, compor custom agents e integrar tools via MCP.

Próxima Trilha:

Trilha 3 — Avançado II: operação, observabilidade e escala

Como colocar tudo isso em produção sem queimar a noite de alguém. Cost control, incident playbooks, multi-tenant.

← Módulo Anterior Voltar para Trilha Próxima Trilha →