Why 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, plus codespar_get_started, the onboarding planner: it moves no money and is counted apart.

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

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 for that rail (e.g. Asaas for Pix in Brazil, Conekta for card 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, plus codespar_get_started

Each one, on its own page

Each meta-tool has its own page with the argument shape, the result shape, how it routes between rails, and what the operator has to configure. This page does not repeat that: two copies of one reference diverge, and the one with less detail wins by being closer.

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.

import { CodeSpar } from "@codespar/sdk";
const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });
const session = await cs.create("user_123", { servers: ["asaas"] });
// ---cut---
import { tools } from "@codespar/sdk";

const available = await tools(session);

// The 14 meta-tools plus codespar_get_started, on every session, whatever `servers` holds.
// A provider's own tools are not in this list: call them by name,
// `<server>/<tool>`, and the catalog resolves them.
//   "stripe/create_subscription"
//   "asaas/get_balance"
//   "mercado-pago/create_preference"
//   "melhor-envio/calculate_deadline"

Next steps