Skip to main content
code<spar>
DocsServersReferenceCookbooksSandbox
Concepts

Tools & Meta-Tools

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

3 min read · updated

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 9 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 9 stable interfaces regardless of how many providers are connected.

Why 9 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 9 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-tools9~1,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 9 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_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_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 via NFe.io, 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

{
  "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 communicates with SEFAZ (Brazil's tax authority) in real time. Latency can reach 2 seconds during peak hours. session.execute() waits for the authorization 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 9 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 (9 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

Last updated on

Projects

Projects are the second level of CodeSpar's 2-level tenancy model -- an isolation boundary inside an organization for API keys, connections, triggers, sessions, and events.

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 9 meta-tools, not 99 raw toolsContext window economicsRouting abstractionThe 9 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