Treeunfe API home pagelight logo
  1. IA e MCP
  2. Agente próprio com a API do Claude

Com o conector MCP da API do Claude, o seu backend envia uma mensagem e o Claude chama as ferramentas da Treeunfe sozinho. Você não precisa escrever o loop de ferramentas nem rodar um cliente MCP: a conexão com o servidor é feita pela Anthropic.

​
Antes de começar

  • Uma chave da API do Claude (ANTHROPIC_API_KEY), criada no Console da Anthropic.
  • A API Key da organization Treeunfe (TREEUNFE_API_KEY), de preferência de homologação.

​
Como funciona

A requisição leva duas partes que precisam andar juntas:

ParâmetroO que faz
mcp_serversDiz onde está o servidor (url), dá um nome a ele (name) e envia a chave em authorization_token. A chave vai como Authorization: Bearer.
toolsUm item mcp_toolset com o mesmo nome do servidor, liberando as ferramentas dele para o Claude.

O conector é beta e precisa do header anthropic-beta: mcp-client-2025-11-20.

​
Exemplo

  • Python

  • TypeScript

pip install anthropic

import os
import anthropic

client = anthropic.Anthropic()  # lê ANTHROPIC_API_KEY

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["mcp-client-2025-11-20", "server-side-fallback-2026-07-01"],
    fallbacks="default",
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.treeunfe.com.br/mcp",
            "name": "treeunfe",
            "authorization_token": os.environ["TREEUNFE_API_KEY"],
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "treeunfe"}],
    messages=[
        {
            "role": "user",
            "content": "Consulte as últimas 5 NF-e emitidas este mês e resuma valor e status de cada uma.",
        }
    ],
)

if response.stop_reason == "refusal":
    print("O pedido foi recusado.")
else:
    for block in response.content:
        if block.type == "text":
            print(block.text)

fallbacks: "default" faz a API tentar outro modelo do Claude se o pedido for recusado pelo modelo principal. Você pode remover esse campo e o beta server-side-fallback-2026-07-01 se não quiser esse comportamento.

​
Limitar as ferramentas

Para um agente que só consulta, deixe todas as ferramentas desligadas por padrão e ligue só as de leitura com default_config e configs:

tools=[
    {
        "type": "mcp_toolset",
        "mcp_server_name": "treeunfe",
        "default_config": {"enabled": False},
        "configs": {
            "NOME_DA_FERRAMENTA_DE_CONSULTA": {"enabled": True},
        },
    }
]

Troque NOME_DA_FERRAMENTA_DE_CONSULTA pelo nome que aparece na lista de ferramentas do servidor. Isso soma com o escopo da chave: mesmo que a ferramenta esteja ligada, uma chave sem nfe:emit não emite.

Com o conector MCP, o Claude chama as ferramentas sem pedir aprovação. Para emitir em produção, prefira uma etapa em que uma pessoa confirma os dados da nota antes do envio, ou use uma chave só com nfe:read no agente e emita pela API REST depois da confirmação.