CodeSpar provides 6 meta-tools that abstract 57 MCP servers into a unified commerce interface, reducing context window cost and simplifying agent development.

Tools & Meta-Tools

CodeSpar integrates 57 MCP servers covering payments, fiscal compliance, logistics, messaging, banking, ERP, and crypto across Latin America. Instead of requiring your agent to understand each server's API individually, CodeSpar provides 6 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), Correios (shipping), and Twilio (notifications). 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 6 stable interfaces regardless of how many providers are connected.

Why 6 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 6 fixed interfaces that never change regardless of how many servers are connected:

Approach	Tools in context	Tokens consumed	Agent complexity
Raw server tools (5 servers)	50-75	10,000-30,000	Agent must know each provider
Meta-tools	6	~1,200	Agent 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:

Inspects the arguments to determine payment method and region
Selects the best available provider (e.g., Asaas for Pix in Brazil, Conekta for SPEI in Mexico)
Translates the request to the provider's native API format
Normalizes the response into a consistent schema
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 6 meta-tools

Meta-tool	Purpose	Typical latency
`codespar_discover`	Find available tools, servers, and capabilities for a commerce domain	50-100ms
`codespar_checkout`	Create hosted checkout sessions and payment links	300-800ms
`codespar_pay`	Process direct payments via Pix, boleto, card, SPEI, or wallet	400-1200ms
`codespar_invoice`	Issue fiscal documents (NF-e, NFS-e, CFDI)	500-2000ms
`codespar_ship`	Quote shipping rates, create labels, track packages	200-600ms
`codespar_notify`	Send notifications via WhatsApp, SMS, or email	100-300ms

`codespar_discover`

The discovery tool helps agents explore what commerce capabilities are available. It is typically the first tool an agent calls in a new conversation to understand the landscape before taking action.

Input schema

Field	Type	Required	Description
`domain`	`string`	Yes	Commerce domain to discover. One of: `payments`, `fiscal`, `logistics`, `messaging`, `banking`, `erp`, `crypto`

Example

const result = await session.execute({
  name: "codespar_discover",
  arguments: { domain: "payments" },
});

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": { "domain": "payments" }
  }'

Response

{
  "result": {
    "domain": "payments",
    "servers": [
      {
        "id": "stripe",
        "name": "Stripe",
        "status": "connected",
        "capabilities": ["checkout", "subscriptions", "refunds", "pix", "boleto", "cards"]
      },
      {
        "id": "mercadopago",
        "name": "Mercado Pago",
        "status": "connected",
        "capabilities": ["pix", "boleto", "checkout", "wallet", "installments"]
      },
      {
        "id": "asaas",
        "name": "Asaas",
        "status": "connected",
        "capabilities": ["pix", "boleto", "subscriptions"]
      }
    ],
    "meta_tools": ["codespar_checkout", "codespar_pay"],
    "total_tools": 37
  }
}

Supported domains: payments, fiscal, logistics, messaging, banking, erp, crypto

codespar_discover counts as a tool call because it queries live server data. Cache the response for the duration of the conversation to avoid redundant calls.

`codespar_checkout`

Creates hosted checkout sessions with pre-built payment pages. The checkout URL can be shared with end users or embedded in your application. CodeSpar routes to the appropriate provider's hosted checkout.

Input schema

Field	Type	Required	Description
`product`	`string`	Yes	Product or plan name displayed on the checkout page
`amount`	`number`	Yes	Amount in the currency's smallest unit (e.g., centavos: 9990 = R$99.90)
`currency`	`string`	Yes	ISO 4217 currency code: `BRL`, `MXN`, `ARS`, `USD`
`provider`	`string`	No	Force a specific provider (`stripe`, `mercadopago`). Auto-selected if omitted
`success_url`	`string`	No	URL to redirect after successful payment
`cancel_url`	`string`	No	URL to redirect if the customer cancels
`customer_email`	`string`	No	Pre-fill the email field on the checkout page
`metadata`	`object`	No	Key-value pairs attached to the checkout for your reference

Example

const result = await session.execute({
  name: "codespar_checkout",
  arguments: {
    provider: "stripe",
    product: "Growth Plan",
    amount: 49900,
    currency: "BRL",
    success_url: "https://myapp.com/success",
    cancel_url: "https://myapp.com/cancel",
  },
});

Response

{
  "result": {
    "checkout_url": "https://checkout.stripe.com/c/pay_a1b2c3d4e5",
    "session_id": "cs_live_a1b2c3",
    "provider": "stripe",
    "amount": 49900,
    "currency": "BRL",
    "expires_at": "2026-04-15T12:00:00Z"
  }
}

Routing behavior

Currency	Default provider	Fallback
`BRL`	Mercado Pago	Stripe
`MXN`	Conekta	Stripe
`ARS`	Mercado Pago	--
`USD`	Stripe	--

`codespar_pay`

Processes payments directly without a hosted checkout page. Supports Pix, boleto, credit card, SPEI, and wallet methods. Unlike codespar_checkout, this tool processes the payment immediately and returns a payment object (or a Pix QR code / boleto PDF for async methods).

Input schema

Field	Type	Required	Description
`method`	`string`	Yes	Payment method: `pix`, `boleto`, `card`, `spei`, `wallet`
`amount`	`number`	Yes	Amount in smallest currency unit (centavos)
`currency`	`string`	Yes	ISO 4217 currency code
`description`	`string`	No	Payment description shown to the customer
`customer_email`	`string`	No	Customer email for receipt delivery
`customer_cpf`	`string`	No	Customer CPF (required for boleto in Brazil)
`provider`	`string`	No	Force a specific provider. Auto-selected if omitted
`metadata`	`object`	No	Key-value pairs for your reference

Example -- Pix payment

const result = await session.execute({
  name: "codespar_pay",
  arguments: {
    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`

Method	Region	Routes to
`pix`	Brazil	Asaas, Mercado Pago, Stripe (in priority order)
`boleto`	Brazil	Asaas, PagSeguro, Stripe
`card`	Any	Stripe, Mercado Pago, Pagarme
`spei`	Mexico	Conekta, Stripe
`wallet`	Any	Mercado 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_invoice`

Issues fiscal documents required by law in Latin American countries. In Brazil, this means NF-e (Nota Fiscal Eletronica for goods) and NFS-e (Nota Fiscal de Servicos for services). In Mexico, CFDI (Comprobante Fiscal Digital por Internet).

Input schema

Field	Type	Required	Description
`type`	`string`	Yes	Document type: `nfe`, `nfse`, `cfdi`
`items`	`array`	Yes	Line items with `description`, `quantity`, `unit_price`, and tax classification
`customer`	`object`	Yes	Customer data: `name`, `email`, and tax ID (`cpf`/`cnpj` for Brazil, `rfc` for Mexico)
`provider`	`string`	No	Force a specific fiscal provider

Example -- Brazilian NF-e

const result = await session.execute({
  name: "codespar_invoice",
  arguments: {
    type: "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. Use session.execute() (not send()) so your agent waits for the authorization confirmation.

`codespar_ship`

Quotes shipping rates from multiple carriers, creates shipping labels, and tracks packages. Supports Correios, Jadlog, Loggi, Mercado Envios, and international carriers.

Input schema

Field	Type	Required	Description
`action`	`string`	Yes	Operation: `quote`, `create_label`, `track`
`origin_zip`	`string`	Conditional	Origin postal code (required for `quote` and `create_label`)
`destination_zip`	`string`	Conditional	Destination postal code (required for `quote` and `create_label`)
`weight_kg`	`number`	Conditional	Package weight in kg (required for `quote`)
`dimensions`	`object`	No	Package dimensions: `length`, `width`, `height` in cm
`carrier`	`string`	Conditional	Carrier ID (required for `create_label`)
`service`	`string`	Conditional	Service level (required for `create_label`): `SEDEX`, `PAC`, etc.
`tracking_code`	`string`	Conditional	Tracking code (required for `track`)

Example -- get quotes

const quotes = await session.execute({
  name: "codespar_ship",
  arguments: {
    action: "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({
  name: "codespar_ship",
  arguments: {
    action: "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

Field	Type	Required	Description
`channel`	`string`	Yes	Delivery channel: `whatsapp`, `sms`, `email`
`to`	`string`	Yes	Recipient: phone number (E.164 format) or email address
`template`	`string`	Yes	Template identifier (e.g., `order_confirmation`, `order_shipped`, `payment_received`)
`variables`	`object`	No	Key-value pairs to populate template placeholders
`language`	`string`	No	Template language: `pt-BR`, `es-MX`, `en`. Defaults to `pt-BR`

Example

await session.send({
  name: "codespar_notify",
  arguments: {
    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.

Server-specific tools

In addition to the 6 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 (6 tools)
// Server-specific tools depend on connected servers
// Examples:
//   "stripe_create_subscription"
//   "stripe_create_refund"
//   "mercadopago_create_preference"
//   "correios_calculate_deadline"

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

Next steps

Sessions -- How to create sessions and connect servers
Servers API -- Browse the full server catalog
Authentication -- API keys and provider credentials
Glossary -- Definitions for meta-tool, MCP, BACR, and other terms

Tools & Meta-Tools

On this page