AGENTUM MCP Server
This server lets AI agents call real AGENTUM APIs via MCP to fetch Brazilian and global official data, paying per call in USDC on Base mainnet through x402.
Brazilian company data:
verificar_cnpj(registration status, Simples Nacional, address) andbusiness_intelligence(full CNPJ data + partners + AI summary).Brazilian compliance:
company_intelligence_brchecks TCU, CNJ, CEIS, CNEP, and CVM — facts only.Address validation:
verificar_cepreturns a full Brazilian address from a CEP.CPF validation:
validar_cpfchecks the CPF check digits only, without consulting personal data.Economic and financial data:
taxas_brasil(Selic, CDI, commercial dollar),economic_data(World Bank GDP, inflation, unemployment, population), andfx_rates(ECB official exchange rates).Global company tools:
vat_validate(real-time EU VAT validation via VIES) andcompany_enrich(global company identification via LEI/GLEIF).Secure pay-per-use model: no API key or subscription; each call is checked against the exact expected network, asset, recipient, and price before signing with your local USDC wallet on Base.
Enables pay-per-call access to the AGENTUM data APIs by signing x402 payment authorizations on-chain from a local Ethereum wallet — each tool call settles a real USDC payment on Base mainnet (eip155:8453), with the payment facilitator sponsoring gas. The server validates the returned charge (chain, asset, recipient, and per-route amount cap) before signing, and the private key never leaves the local machine.
@agentum/mcp-server
Servidor MCP (Model Context Protocol) que expõe as APIs reais da AGENTUM (dados brasileiros e globais: CNPJ, CEP, taxas oficiais, CPF, inteligência empresarial, LEI, VAT europeu, câmbio, indicadores econômicos) como ferramentas que qualquer agente de IA com suporte a MCP (Claude Desktop, Claude Code, Cursor, etc.) pode chamar diretamente — pagando por uso, em USDC real, via protocolo x402.
Sem chave de API, sem cadastro, sem assinatura mensal. Cada chamada é um pagamento on-chain (Base mainnet) na hora, direto do pacote publicado no npm — não precisa clonar este repositório pra usar.
Quick Start (menos de 5 minutos)
Você precisa de duas coisas: uma carteira Ethereum dedicada com um pouco
de USDC na rede Base (mainnet, eip155:8453 — poucos centavos já
bastam pra testar; o facilitador de pagamento patrocina o gás, só precisa
de USDC mesmo), e um cliente com suporte a MCP. Escolha o seu:
⚠️ Em toda opção abaixo, a chave fica em texto puro no arquivo de config ou no comando. Nunca coloque esse arquivo (nem um comando com a chave escrita nele) num repositório git ou num histórico de shell compartilhado/sincronizado — uma chave vazada dá acesso direto à sua carteira, sem precisar do servidor MCP pra nada.
Edite (ou crie) ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"agentum": {
"command": "npx",
"args": ["-y", "@agentum/mcp-server"],
"env": {
"AGENTUM_MCP_WALLET_KEY": "0xSUACHAVEPRIVADAAQUI"
}
}
}
}Reinicie o Claude Desktop. Pronto — pergunte algo como "verifica o CNPJ 68964713000109" e o Claude vai chamar a ferramenta sozinho.
Digitar a chave direto no comando grava ela em texto puro no seu
~/.zsh_history/~/.bash_history (arquivo que muitos setups de dotfiles
sincronizam ou versionam sem perceber). Use read -s — ele não ecoa o que
você digita/cola, e o shell grava no histórico o comando como digitado
(com $AGENTUM_MCP_WALLET_KEY literal), não o valor já substituído:
read -s -p "Cole sua chave privada (0x...): " AGENTUM_MCP_WALLET_KEY && echo
export AGENTUM_MCP_WALLET_KEY
claude mcp add agentum -e AGENTUM_MCP_WALLET_KEY=$AGENTUM_MCP_WALLET_KEY -- npx -y @agentum/mcp-server(-e/--env vem antes do --; tudo depois do -- é passado intacto pro
servidor.)
Prefira ~/.cursor/mcp.json (vale pra todos os projetos e não fica dentro
de um repositório git). Só use a versão no projeto (.cursor/mcp.json)
se você garantir .cursor/ no .gitignore antes do primeiro commit —
uma vez que a chave entra no histórico do git, remover o arquivo depois
não resolve (fica no histórico; precisaria reescrever com git filter-repo
ou equivalente).
{
"mcpServers": {
"agentum": {
"command": "npx",
"args": ["-y", "@agentum/mcp-server"],
"env": {
"AGENTUM_MCP_WALLET_KEY": "0xSUACHAVEPRIVADAAQUI"
}
}
}
}Nunca use uma carteira que também guarda fundos importantes — use uma dedicada, só com o USDC necessário pro uso que você pretende fazer.
Exemplo real de ponta a ponta
Prompt pro agente: "verifica o CNPJ 68964713000109"
O agente decide sozinho chamar verificar_cnpj({ cnpj: "68964713000109" })
— o servidor assina um pagamento real de $0.02 USDC na Base, a AGENTUM
processa e devolve, e o agente recebe de volta (dado real, de produção):
{
"cnpj": "68.964.713/0001-09",
"razao_social": "AGENTUM LTDA",
"situacao": "ATIVA",
"data_situacao": "03/09/2026",
"abertura": "03/09/2026",
"natureza_juridica": "206-2 - Sociedade Empresária Limitada",
"uf": "SP",
"municipio": "SERTAOZINHO",
"atividade_principal": "Desenvolvimento e licenciamento de programas de computador customizáveis",
"fonte": "receitaws"
}Nenhum código de pagamento escrito por você — o servidor cuida do desafio x402, da assinatura e da checagem de segurança (ver seção "Segurança" abaixo) sozinho.
Related MCP server: veradata
Ferramentas disponíveis
Ferramenta | Preço | Descrição |
| $0.02 | Situação cadastral, Simples Nacional, endereço |
| $0.01 | Selic, CDI, dólar comercial (Banco Central) |
| $0.01 | Endereço completo a partir do CEP |
| $0.01 | Confere dígito verificador (não consulta dado pessoal) |
| $0.05 | CNPJ completo + sócios + resumo gerado por IA |
| $0.01 | Câmbio oficial (Banco Central Europeu), qualquer par de moedas |
| $0.01 | PIB, inflação, desemprego, população (Banco Mundial), qualquer país |
| $0.01 | Validação de VAT europeu em tempo real (VIES, oficial da UE) |
| $0.01 | Identificação global de empresa via LEI (GLEIF), qualquer país |
| $0.02 | CNPJ + compliance (TCU, CNJ, CEIS, CNEP, CVM) — só fatos, sem score |
| $0.15 | Veredito de contraparte (CNPJ, LEI ou nome) — band clear/flagged/insufficient_data, nunca um score fabricado |
company_intelligence_br e preflight usam uma carteira de destino diferente das outras (sistema AGENTUM Business, processo/domínio separados de propósito) — o servidor já sabe disso e valida cada rota contra a carteira certa dela.
Rodando a partir do código-fonte (desenvolvimento)
Se você clonou este repositório em vez de usar o pacote publicado (npx),
a configuração aponta pro arquivo local em vez de deixar o npx resolver:
npm install
read -s -p "Cole sua chave privada (0x...): " AGENTUM_MCP_WALLET_KEY && echo
export AGENTUM_MCP_WALLET_KEY(export VAR=0x... digitado direto fica gravado em texto puro no seu
histórico de shell — read -s evita isso, ver aviso no Quick Start acima.)
{
"mcpServers": {
"agentum": {
"command": "node",
"args": ["/caminho/completo/pra/mcp-server/index.js"],
"env": {
"AGENTUM_MCP_WALLET_KEY": "0xSUACHAVEPRIVADAAQUI"
}
}
}
}Segurança
Antes de assinar qualquer pagamento, o servidor confere que a cobrança devolvida pela AGENTUM é exatamente: rede Base mainnet, ativo USDC, destinatário a carteira oficial da AGENTUM, e valor dentro do teto conhecido daquela rota específica. Qualquer coisa fora disso e a chamada é abortada sem assinar nada — mesmo que o servidor da AGENTUM esteja comprometido ou com bug, sua carteira nunca paga a outro destinatário nem um valor fora do esperado.
Sua chave privada nunca sai da sua máquina/processo local — não é enviada pra AGENTUM nem pra ninguém, só assina localmente as autorizações de pagamento x402.
Rodar standalone (debug)
node index.jsFica esperando conexão MCP via stdio (é assim que um client MCP conecta).
Available Tools
5 toolsbusiness_intelligenceInteligência empresarial (CNPJ completo)B
Inteligência empresarial brasileira completa: situação cadastral, endereço, atividades, sócios (CPF sempre mascarado pela própria Receita Federal) e resumo gerado por IA a partir só de dados oficiais. Pagamento real de $0.05 em USDC (Base mainnet).
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes | CNPJ brasileiro, 14 dígitos, com ou sem pontuação |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral aspects: it is a paid operation (real payment of $0.05), CPF data is masked by Receita Federal, and the summary is generated from official data only. However, it does not explicitly state whether the operation is read-only, nor does it mention rate limits or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and front-loaded with the main purpose, followed by the key data points and the payment notice. The payment detail is relevant and not extraneous, though the sentence could be slightly streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input and no output schema, the description adequately covers what the tool returns and the cost implication. It does not specify the output format, but this is not critical for a tool that returns a summary of business data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, cnpj, is fully described in the schema with details on format and punctuation flexibility. The description adds no further meaning beyond the schema, but the schema itself is clear enough for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool provides comprehensive Brazilian business intelligence, including registration status, address, activities, partners, and an AI-generated summary. It distinguishes itself by emphasizing the completeness and official data source, though it lacks an explicit verb indicating the action performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a real payment of $0.05 in USDC, implying a cost consideration, but does not provide explicit guidance on when to use this tool versus the sibling tools like verificar_cnpj or validar_cpf. No conditions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
taxas_brasilTaxas oficiais do BrasilA
Consulta taxas oficiais brasileiras em tempo real (Selic, CDI, dólar comercial). Pagamento real de $0.01 em USDC (Base mainnet).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It excels here by disclosing that the call incurs a REAL payment of $0.01 USDC on Base mainnet — a critical trait an agent must know before invoking, since it has actual financial consequences. It could additionally describe return format or failure behavior, but the cost disclosure is a substantial and well-placed transparency win.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The first sentence front-loads the purpose (real-time official Brazilian rates with concrete examples) and the second delivers the essential operational caveat (the $0.01 USDC payment). Every word earns its place, and the critical cost warning is not buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter query tool with no annotations and no output schema, the description covers the essential ground: what it queries (Selic, CDI, commercial dollar) and the non-obvious cost of invocation. The only gap is the unspecified return format, but given the simplicity of the tool and the strong cost disclosure, this is a minor omission rather than a blocking one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty schema, so the rubric baseline of 4 applies. There are no parameters for the description to document, and the description correctly adds no redundant parameter information. Nothing is missing on this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('consulta') and a precise resource ('taxas oficiais brasileiras em tempo real') with enumerated examples (Selic, CDI, dólar comercial). This clearly differentiates it from siblings like verificar_cnpj, verificar_cep, validar_cpf, and business_intelligence, which concern entirely different domains. An agent can immediately know what this tool does and when it applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is clear enough that an agent can infer when to use it — whenever official Brazilian rates (Selic, CDI, dollar) are needed. However, there is no explicit when-to-use or when-not-to-use language, and no alternatives are named. The sibling differentiation is implicit via domain, not explicit in the text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
validar_cpfValidar CPFA
Confirma se um CPF brasileiro é matematicamente válido (dígito verificador) — não consulta dado pessoal de ninguém. Pagamento real de $0.01 em USDC (Base mainnet).
| Name | Required | Description | Default |
|---|---|---|---|
| cpf | Yes | CPF brasileiro, 11 dígitos, com ou sem pontuação |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses real payment of $0.01 USDC on Base mainnet and states no personal data is consulted. Since no annotations exist, the description fully carries the burden of exposing side effects and non-effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences convey purpose, scope, and cost without unnecessary detail. Every clause adds relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's core behavior, input format, and payment side effect. It does not specify the output shape or return value, which is a minor gap given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'cpf' is described with format details (11 digits, with or without punctuation), covering both type and acceptable input. Schema coverage is complete for the one parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool validates Brazilian CPF mathematically and explicitly notes it does not query personal data. The verb 'validar' and scope are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use when CPF validation is needed and clarifies it is mathematical-only with no data lookup. It does not explicitly compare to sibling tools, but the names make the distinction evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verificar_cepVerificar CEPA
Valida um CEP/endereço brasileiro em tempo real. Pagamento real de $0.01 em USDC (Base mainnet).
| Name | Required | Description | Default |
|---|---|---|---|
| cep | Yes | CEP brasileiro, 8 dígitos, com ou sem hífen |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It does disclose a real payment of $0.01 in USDC on Base mainnet, which is an important side effect, but it does not clarify other behavioral aspects such as failure modes or whether any state changes occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it front-loads the core purpose in the first sentence and adds the cost detail in the second. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify what the caller receives, but it only says 'Valida um CEP/endereço'. It is ambiguous whether the result is a boolean, an address object, or an error response. The payment information is useful but does not fully compensate for this gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the cep parameter as 'CEP brasileiro, 8 dígitos, com ou sem hífen', so coverage is high. The description adds little beyond the schema, keeping the baseline score at 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states a specific action ('Valida um CEP/endereço brasileiro') and resource. The tool is easily distinguished from siblings like validar_cpf or verificar_cnpj by the CEP/address focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool name and description—use when validating a Brazilian CEP/address—but there is no explicit mention of when to prefer this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verificar_cnpjVerificar CNPJA
Verifica um CNPJ brasileiro em tempo real (situação cadastral, Simples Nacional, endereço). Pagamento real de $0.02 em USDC (Base mainnet).
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes | CNPJ brasileiro, 14 dígitos, com ou sem pontuação |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses a critical side effect: a real payment of $0.02 in USDC on Base mainnet. It also states 'real time' behavior, which implies a network call. No other hidden side effects are apparent, and the verification nature suggests a read-only operation. Given no annotations exist, this transparency is fully carried by the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, efficiently conveying purpose, output details, and cost. There is no fluff or repetition; every word adds value. The structure is clean and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool, the description covers all necessary aspects: what it does, what data it returns, and the associated cost. It does not require an output schema or error handling details for basic usage. The context is sufficient for an agent to decide and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a complete description of the 'cnpj' parameter (14 digits, with or without punctuation). The tool description adds no further meaning about the parameter itself, such as formatting examples or validation rules. Baseline score is appropriate since schema coverage is 100% and the parameter is straightforward.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: verifying a Brazilian CNPJ in real time, and lists the specific data returned (registration status, Simples Nacional, address). This leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While it doesn't explicitly say 'use this instead of other tools,' the focus on CNPJ and the mention of a real payment ($0.02) provide implicit guidance. The sibling tools (validar_cpf, verificar_cep) make the domain clear, and a CNPJ verification naturally falls to this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v1.0.0- First observed
business_intelligence - First observed
taxas_brasil - First observed
validar_cpf - First observed
verificar_cep - First observed
verificar_cnpj
TDQS
Scored across 5 tools
The tools verificar_cnpj and business_intelligence have significant overlap, as business_intelligence includes CNPJ cadastral status, address, and activities, making it a superset of verificar_cnpj. The other tools (taxas_brasil, verificar_cep, validar_cpf) are clearly distinct, but the ambiguity between these two CNPJ-related tools could lead to misselection.
Naming is inconsistent across language and pattern: three tools use Portuguese verbs (verificar_cnpj, verificar_cep, validar_cpf), one uses a Portuguese noun phrase (taxas_brasil), and one uses English (business_intelligence). This mix of languages and grammatical forms breaks any predictable pattern.
With only 5 tools, the server is well-scoped for its purpose of providing Brazilian business and tax data lookups. Each tool covers a distinct data domain (CNPJ, CEP, CPF, taxes, and a comprehensive business report), and none feel superfluous or missing to the point of underutilization.
The tool surface covers the core Brazilian identifiers (CNPJ, CPF, CEP) and financial rates, plus an aggregated business intelligence tool. A minor gap is that verificar_cnpj seems redundant with business_intelligence, and there is no tool for other entity types (e.g., IE – state registration), but the primary use cases are well covered.
Maintenance
Related MCP Connectors
Brazilian public data API for AI agents. BCB, IBGE, CVM, B3, compliance. x402 payments on Base.
Brazilian company data (CNPJ): registry lookup, sanctions screening and KYB dossier, paid via x402
8 pay-per-call web intel tools over MCP. Free discovery, calls settle in USDC on Base (x402).
9 pay-per-call company intel tools over MCP. Free discovery, calls settle in USDC on Base (x402).
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceValida CPFs, confirma titularidade, descobre CPF completo a partir de dígitos parciais e resolve CAPTCHA automaticamente, integrando com agentes AI via MCP.22MIT
- FlicenseAqualityBmaintenanceMCP server providing verified Latin American data via x402 micropayments. 4 MCP tools: vera_rates (central bank rates CO/MX/BR/CL/PE), vera_sanctions (OFAC+SARLAFT+CNBV+COAF+UAF screening, EU AI Act Art.13), vera_entity (RUES/CNPJ/RFC enrichment), vera_context (AI market intelligence). $0.02–$0.10 USDC per call.4-
- AlicenseAqualityBmaintenanceAn MCP server for Brazilian company and public procurement data, enabling CNPJ lookup, company search, tender resolution, and more via paid USDC-based API calls.1575MIT
- AlicenseNot gradedqualityCmaintenanceMCP server providing 10 pay-per-call APIs for web scraping, DNS, email validation, and French business data, with autonomous micropayments via the x402 protocol (USDC on Base).1MIT