Skip to main content
Glama
orionlabsai

AGENTUM MCP Server

@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

verificar_cnpj

$0.02

Situação cadastral, Simples Nacional, endereço

taxas_brasil

$0.01

Selic, CDI, dólar comercial (Banco Central)

verificar_cep

$0.01

Endereço completo a partir do CEP

validar_cpf

$0.01

Confere dígito verificador (não consulta dado pessoal)

business_intelligence

$0.05

CNPJ completo + sócios + resumo gerado por IA

fx_rates

$0.01

Câmbio oficial (Banco Central Europeu), qualquer par de moedas

economic_data

$0.01

PIB, inflação, desemprego, população (Banco Mundial), qualquer país

vat_validate

$0.01

Validação de VAT europeu em tempo real (VIES, oficial da UE)

company_enrich

$0.01

Identificação global de empresa via LEI (GLEIF), qualquer país

company_intelligence_br

$0.02

CNPJ + compliance (TCU, CNJ, CEIS, CNEP, CVM) — só fatos, sem score

preflight

$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.js

Fica esperando conexão MCP via stdio (é assim que um client MCP conecta).

Available Tools

5 tools
business_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).

ParametersJSON Schema
NameRequiredDescriptionDefault
cnpjYesCNPJ brasileiro, 14 dígitos, com ou sem pontuação

TDQS

B3.4/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
cpfYesCPF brasileiro, 11 dígitos, com ou sem pontuação

TDQS

A4.7/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
cepYesCEP brasileiro, 8 dígitos, com ou sem hífen

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
cnpjYesCNPJ brasileiro, 14 dígitos, com ou sem pontuação

TDQS

A4.5/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

  1. 5 tool updatesv1.0.0
    • First observedbusiness_intelligence
    • First observedtaxas_brasil
    • First observedvalidar_cpf
    • First observedverificar_cep
    • First observedverificar_cnpj

TDQS

A3.6/5.0

Scored across 5 tools

Disambiguation2/5

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 Consistency2/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    A
    maintenance
    Valida CPFs, confirma titularidade, descobre CPF completo a partir de dígitos parciais e resolve CAPTCHA automaticamente, integrando com agentes AI via MCP.
    22
    MIT
  • F
    license
    A
    quality
    B
    maintenance
    MCP 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
    -
  • A
    license
    A
    quality
    B
    maintenance
    An MCP server for Brazilian company and public procurement data, enabling CNPJ lookup, company search, tender resolution, and more via paid USDC-based API calls.
    15
    75
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    MCP 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).
    1
    MIT