Skip to main content
code<spar>
DocsServersReferenceCookbooksSandbox
Concepts

Tools & Meta-Tools

CodeSpar provides 14 meta-tools that abstract every connected MCP server into a unified commerce interface, reducing context window cost and simplifying agent development.

3 min read
View MarkdownEdit on GitHub

Tools & Meta-Tools

CodeSpar integrates MCP servers covering every major LatAm commerce API — payments, fiscal compliance, logistics, messaging, banking, ERP, and crypto. Instead of requiring your agent to understand each server's API individually, CodeSpar provides 14 meta-tools that intelligently route calls to the right provider.

This design is intentional. A typical commerce workflow in Brazil might touch Stripe (cards), Mercado Pago (Pix), SEFAZ (NF-e), Melhor Envio (shipping), and Z-API (WhatsApp). That is 5 providers, each with 10-20 tools, totaling 50-100 tool definitions in the LLM's context window. Meta-tools compress this to 14 stable interfaces regardless of how many providers are connected.

Why a few meta-tools, not 99 raw tools

Context window economics

Every tool definition consumes tokens in the LLM's context window. A typical MCP server exposes 10-15 tools, each with a JSON Schema input_schema averaging 200-400 tokens. Connect 5 servers and you consume 5,000-15,000 tokens just on tool definitions -- before the conversation even starts.

Meta-tools solve this by providing 14 fixed interfaces that never change regardless of how many servers are connected:

ApproachTools in contextTokens consumedAgent complexity
Raw server tools (5 servers)50-7510,000-30,000Agent must know each provider
Meta-tools14~2,800Agent uses unified interface

Routing abstraction

When your agent calls codespar_pay, CodeSpar inspects the arguments (payment method, currency, amount) and routes to the optimal provider:

  1. Inspects the arguments to determine payment method and region
  2. Selects the best available provider (e.g., Asaas for Pix in Brazil, Conekta for SPEI in Mexico)
  3. Translates the request to the provider's native API format
  4. Normalizes the response into a consistent schema
  5. Returns the result to your agent

Your agent never needs to know which provider handles Pix vs. boleto vs. SPEI. It calls codespar_pay with the intent, and CodeSpar handles the routing.

The 14 meta-tools

Meta-toolPurposeTypical latency
codespar_discoverSemantic + lexical search across the catalog for tools and servers50-150ms
codespar_manage_connectionsInspect connected providers and start connection flows50-200ms
codespar_payOutbound transfers — payouts to recipients via Pix, boleto, SPEI, card, or wallet400-1200ms
codespar_chargeInbound charges — buyer pays merchant via Pix (BRL) or card (USD)400-1200ms
codespar_checkoutSell-side merchant checkout — as a merchant, create a checkout for a shopper to pay you (cart, pricing, tax, payment via Stripe ACP / Asaas / x402)600-2000ms
codespar_shopBuy-side shopping — act as the shopper: search a store and buy, minting the store's real Pix (VTEX guest checkout, Mercado Livre)600-2000ms
codespar_invoiceIssue fiscal documents (NFS-e default, NF-e, CFDI, Factura AR)500-2000ms
codespar_shipDomestic shipping via Melhor Envio (domestic-quote, domestic-label, domestic-track)200-600ms
codespar_notifySend notifications via WhatsApp, SMS, or email100-300ms
codespar_crypto_payCrypto payments via Coinbase Commerce or Bitso300-1000ms
codespar_kycKYC / identity verification via Persona, Sift, Konduto, or Truora300-1500ms
codespar_walletThe agent's governed wallet: balance and Pix key, ledger statement, top-up via minted Pix copia-e-cola100-400ms
codespar_ledgerDouble-entry ledger (Lerian Midaz) — entry, balance, account100-400ms
codespar_issueIssue + control payment cards via our card-issuing partner — virtual/physical/freeze/cancel300-1000ms

codespar_discover

The discovery tool runs semantic and lexical search across the live catalog so an agent can find the right tool or server before taking action. Powered by OpenAI text-embedding-3-small with a pg_trgm lexical fallback; results are biased toward providers already connected to the session.

Input schema

FieldTypeRequiredDescription
querystringYesNatural-language search — e.g. "emit fiscal invoice for services in Brazil" or "send WhatsApp template"
limitnumberNoMaximum number of matches to return (default 10)

Example

const result = await session.execute("codespar_discover", {
  query: "charge a buyer in BRL via Pix",
});
curl -X POST https://api.codespar.dev/v1/sessions/ses_abc123/execute \
  -H "Authorization: Bearer csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "codespar_discover",
    "arguments": { "query": "charge a buyer in BRL via Pix" }
  }'

Response

{
  "result": {
    "matches": [
      {
        "tool": "codespar_charge",
        "server": "asaas",
        "score": 0.91,
        "connected": true,
        "summary": "Inbound Pix charge — buyer pays merchant via Asaas"
      },
      {
        "tool": "codespar_charge",
        "server": "mercadopago",
        "score": 0.88,
        "connected": true,
        "summary": "Inbound Pix charge — buyer pays merchant via Mercado Pago"
      }
    ]
  }
}

codespar_discover counts as a tool call because it queries the live catalog and embedding index. Cache the response for the duration of the conversation to avoid redundant calls.

codespar_manage_connections

Lets the agent introspect which providers the current session has connected and, when a needed provider is missing, kick off a connection flow. Pairs with codespar_discover: discover finds the right tool, manage_connections checks whether it's reachable for this user.

Connection flows surface a deep-link the integrator can render in the dashboard or chat UI; the operator completes auth there and the connection becomes available to subsequent tool calls.

Example

const status = await session.execute("codespar_manage_connections", {
  action: "list",
});

// If a provider is missing, start a connection flow:
const flow = await session.execute("codespar_manage_connections", {
  action: "connect",
  server: "z-api",
});

codespar_pay

Processes outbound payments — money leaving the merchant to a recipient (vendor payout, marketplace seller settlement, refund). Distinct from codespar_charge, which is the inbound counterpart (buyer pays merchant). Supports Pix, boleto, credit card, SPEI, and wallet methods. Returns a payment object (or a Pix QR code / boleto PDF for async methods).

Input schema

FieldTypeRequiredDescription
methodstringYesPayment method: pix, boleto, card, spei, wallet
amountnumberYesAmount in smallest currency unit (centavos)
currencystringYesISO 4217 currency code
descriptionstringNoPayment description shown to the customer
customer_emailstringNoCustomer email for receipt delivery
customer_cpfstringNoCustomer CPF (required for boleto in Brazil)
providerstringNoForce a specific provider. Auto-selected if omitted
metadataobjectNoKey-value pairs for your reference

Example -- Pix payment

const result = await session.execute("codespar_pay", {
  method: "pix",
  amount: 15000,
  currency: "BRL",
  description: "Order #5678",
  customer_email: "maria@example.com",
});

Response

{
  "result": {
    "payment_id": "pay_xyz789",
    "status": "pending",
    "method": "pix",
    "provider": "asaas",
    "pix_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "qr_code_url": "https://api.codespar.dev/qr/pay_xyz789.png",
    "amount": 15000,
    "currency": "BRL",
    "expires_at": "2026-04-15T11:00:00Z"
  }
}

Routing: codespar_pay

MethodRegionRoutes to
pixBrazilAsaas, Mercado Pago, Stripe (in priority order)
boletoBrazilAsaas, PagSeguro, Stripe
cardAnyStripe, Mercado Pago, Pagarme
speiMexicoConekta, Stripe
walletAnyMercado Pago

Omit the provider field to let CodeSpar auto-select the best provider based on payment method, currency, and current availability. Override only when you have a specific business reason (e.g., contractual obligation to a provider).

codespar_charge

Processes inbound charges — the buyer pays the merchant. This is the counterpart to codespar_pay (outbound). Use codespar_charge for ecommerce checkout, marketplace order capture, and any flow where money comes IN. Use codespar_pay for payouts, refunds, or transfers OUT.

Input schema

FieldTypeRequiredDescription
methodstringYesPayment method: pix (BRL) or card (USD)
amountnumberYesAmount in smallest currency unit (centavos for BRL, cents for USD)
currencystringYesISO 4217 currency code: BRL, USD
descriptionstringNoDescription shown to the buyer
customer_emailstringNoBuyer email for receipt delivery
customer_cpfstringNoBuyer CPF (required for some BRL methods)
providerstringNoForce a specific provider. Auto-selected if omitted
metadataobjectNoKey-value pairs for your reference

Example -- inbound Pix charge

const result = await session.execute("codespar_charge", {
  method: "pix",
  amount: 9990,
  currency: "BRL",
  description: "Order #1234",
  customer_email: "ana@example.com",
});

Routing: codespar_charge

MethodCurrencyRoutes to
pixBRLAsaas, Mercado Pago, iugu, Stone
cardUSDStripe

codespar_invoice

Issues fiscal documents required by law in Latin American countries. The default rail is NFS-e (Brazilian Nota Fiscal de Serviços), suitable for most agent-driven SaaS and services flows. Pass rail: "nfe" for product invoices, rail: "cfdi" for Mexico (Facturapi), or rail: "factura_ar" for Argentina (AFIP).

Input schema

FieldTypeRequiredDescription
railstringNoInvoice rail: nfse (default, BR services), nfe (BR products), cfdi (MX), factura_ar (AR)
itemsarrayYesLine items with description, quantity, unit_price, and tax classification
customerobjectYesCustomer data: name, email, and tax ID (cpf/cnpj for Brazil, rfc for Mexico)
providerstringNoForce a specific fiscal provider

Example -- Brazilian NF-e (products)

const result = await session.execute("codespar_invoice", {
  rail: "nfe",
  items: [
    {
      description: "SaaS Subscription - Growth Plan",
      quantity: 1,
      unit_price: 49900,
      ncm: "99900000",
      cfop: "5933",
    },
  ],
  customer: {
    cpf: "123.456.789-00",
    name: "Maria Silva",
    email: "maria@example.com",
  },
});

Response

Illustrative, sandbox-shaped response; the access_key and sefaz_protocol values are placeholders, not real SEFAZ artifacts.

{
  "result": {
    "invoice_id": "inv_nfe_abc123",
    "type": "nfe",
    "status": "authorized",
    "access_key": "35260412345678000195550010000000011234567890",
    "number": 1,
    "series": 1,
    "pdf_url": "https://api.codespar.dev/invoices/inv_nfe_abc123.pdf",
    "xml_url": "https://api.codespar.dev/invoices/inv_nfe_abc123.xml",
    "sefaz_protocol": "135260400000001",
    "issued_at": "2026-04-15T10:45:00Z"
  }
}

NF-e issuance targets SEFAZ (Brazil's tax authority) authorization; today the flow is validated against the provider sandbox, with production SEFAZ authorization on the roadmap. Against production SEFAZ, latency can reach 2 seconds during peak hours. session.execute() waits for the issuance confirmation before returning.

codespar_ship

Domestic shipping via Melhor Envio. Three rails are picked by the action argument:

  • domestic-quote — quote rates across Melhor Envio's carriers (Correios, Jadlog, Loggi, etc.)
  • domestic-label — purchase a shipping label after picking a quote
  • domestic-track — fetch tracking events for an existing shipment

Input schema

FieldTypeRequiredDescription
actionstringYesRail: domestic-quote, domestic-label, domestic-track
origin_zipstringConditionalOrigin postal code (required for quote and label)
destination_zipstringConditionalDestination postal code (required for quote and label)
weight_kgnumberConditionalPackage weight in kg (required for quote)
dimensionsobjectNoPackage dimensions: length, width, height in cm
servicestringConditionalMelhor Envio service ID (required for label)
tracking_codestringConditionalTracking code (required for domestic-track)

Example -- get quotes

const quotes = await session.execute("codespar_ship", {
  action: "domestic-quote",
  origin_zip: "01310-100",
  destination_zip: "22041-080",
  weight_kg: 2.5,
  dimensions: { length: 30, width: 20, height: 15 },
});

Response

{
  "result": {
    "quotes": [
      {
        "carrier": "correios",
        "service": "SEDEX",
        "price": 4590,
        "currency": "BRL",
        "estimated_days": 2,
        "deadline": "2026-04-17"
      },
      {
        "carrier": "correios",
        "service": "PAC",
        "price": 2890,
        "currency": "BRL",
        "estimated_days": 5,
        "deadline": "2026-04-20"
      },
      {
        "carrier": "jadlog",
        "service": ".Package",
        "price": 3200,
        "currency": "BRL",
        "estimated_days": 3,
        "deadline": "2026-04-18"
      }
    ]
  }
}

Example -- track a package

const tracking = await session.execute("codespar_ship", {
  action: "domestic-track",
  tracking_code: "BR123456789",
});

Response

{
  "result": {
    "tracking_code": "BR123456789",
    "carrier": "correios",
    "status": "in_transit",
    "events": [
      {
        "timestamp": "2026-04-15T08:00:00Z",
        "description": "Object dispatched to Brazil",
        "location": "Sao Paulo - SP"
      },
      {
        "timestamp": "2026-04-14T16:00:00Z",
        "description": "Object posted",
        "location": "Sao Paulo - SP"
      }
    ]
  }
}

codespar_notify

Sends notifications through WhatsApp, SMS, or email using pre-approved templates. Ideal for transactional messages like order confirmations, shipping updates, and payment receipts.

Input schema

FieldTypeRequiredDescription
channelstringYesDelivery channel: whatsapp, sms, email
tostringYesRecipient: phone number (E.164 format) or email address
templatestringYesTemplate identifier (e.g., order_confirmation, order_shipped, payment_received)
variablesobjectNoKey-value pairs to populate template placeholders
languagestringNoTemplate language: pt-BR, es-MX, en. Defaults to pt-BR

Example

await session.execute("codespar_notify", {
  channel: "whatsapp",
  to: "+5511999999999",
  template: "order_shipped",
  variables: {
    customerName: "Maria",
    trackingCode: "BR123456789",
    estimatedDelivery: "2026-04-18",
  },
});

Response (via session.execute())

{
  "result": {
    "message_id": "msg_ntf_abc123",
    "channel": "whatsapp",
    "status": "delivered",
    "delivered_at": "2026-04-15T10:46:02Z"
  }
}

Use session.send() (fire-and-forget) for notifications when you do not need delivery confirmation. Use session.execute() when you need to verify the message was delivered before continuing the workflow.

codespar_crypto_pay

Crypto payments routed through Coinbase Commerce or Bitso. Use when the buyer or recipient settles in crypto rather than fiat — e.g. cross-border B2B settlement or stablecoin payouts.

Example

const result = await session.execute("codespar_crypto_pay", {
  amount: "0.05",
  currency: "ETH",
  destination_address: "0x...",
});

Routes to: Coinbase Commerce, Bitso.

codespar_kyc

Identity verification across multiple providers. Use as a gate before high-value codespar_charge / codespar_pay calls or when a regulated workflow demands proof of identity.

Example

const verification = await session.execute("codespar_kyc", {
  customer_email: "ana@example.com",
  customer_cpf: "123.456.789-00",
  level: "id_verification",
});

Routes to: Persona, Sift, Konduto, Truora.

Poll the verification result via GET /v1/tool-calls/:id/verification-status or session.verificationStatus().

Server-specific tools

In addition to the 14 meta-tools, each connected MCP server exposes its own native tools. These are useful when you need provider-specific features that meta-tools do not cover, such as Stripe subscription management or Mercado Pago installment configuration.

const tools = await session.tools();

// Meta-tools are always available (14 tools)
// Server-specific tools depend on connected servers
// Examples:
//   "stripe_create_subscription"
//   "stripe_create_refund"
//   "mercadopago_create_preference"
//   "melhor_envio_calculate_deadline"

The tool schema field is input_schema (snake_case), following the MCP specification. Not inputSchema (camelCase).

Next steps

CONCEPT
Sessions
Create sessions, connect servers, drive the agent loop.
REFERENCE
Servers API
Browse the full MCP server catalog — every LatAm rail.
CONCEPT
Authentication
API keys and how provider credentials get stored.
COOKBOOK
Pix Payment Agent
codespar_pay via Asaas — simplest real-world example.
COOKBOOK
E-Commerce Checkout
All four commerce meta-tools in one conversation.
COOKBOOK
Cross-Border Fintech
codespar_pay USD → BRL with explicit FX math.
COOKBOOK
Marketplace Payout
Platform fee + seller payout as two settled transactions.
GLOSSARY
Glossary
Meta-tool, MCP, BACR, and other concept definitions.
Edit on GitHub

Chat-loop Governance

Policy rules, audit-chain capture, and commerce-memory predicates now fire on every chat-loop tool call. What that changes for customers whose policies were tuned for direct-execute traffic, and how to verify.

Tool Router

Route tool calls and raw HTTP requests through a managed session — auth is injected server-side, so your agent never touches provider credentials.

On this page

Tools & Meta-ToolsWhy a few meta-tools, not 99 raw toolsContext window economicsRouting abstractionThe 14 meta-toolscodespar_discoverInput schemaExampleResponsecodespar_manage_connectionsExamplecodespar_payInput schemaExample -- Pix paymentResponseRouting: codespar_paycodespar_chargeInput schemaExample -- inbound Pix chargeRouting: codespar_chargecodespar_invoiceInput schemaExample -- Brazilian NF-e (products)Responsecodespar_shipInput schemaExample -- get quotesResponseExample -- track a packageResponsecodespar_notifyInput schemaExampleResponse (via session.execute())codespar_crypto_payExamplecodespar_kycExampleServer-specific toolsNext steps
Tools & Meta-Tools | CodeSpar