Frequently Asked Questions

General

What is CodeSpar?

CodeSpar is commerce infrastructure for AI agents in Latin America. It provides a unified SDK and API that gives AI agents (Claude, GPT, Gemini, or any LLM) the ability to process payments, issue invoices, ship packages, and send notifications through 57 integrated MCP servers. Think of it as "Stripe for AI agents" but covering the full commerce stack -- payments, fiscal, logistics, and messaging -- with deep Latin American coverage.

How is CodeSpar different from Composio or Toolhouse?

CodeSpar is purpose-built for commerce in Latin America. General-purpose tool platforms offer breadth across many domains. CodeSpar goes deep on a specific vertical:

• Regional payment methods: Native support for Pix, boleto, SPEI, OXXO, and installment plans
• Fiscal compliance: Automated NF-e, NFS-e, and CFDI issuance -- legally required in Brazil and Mexico
• 57 commerce-specific MCP servers across 7 categories (payments, fiscal, logistics, messaging, banking, ERP, crypto)
• 6 meta-tools that abstract provider routing -- your agent does not need to know about each provider's API
• Context window efficiency: 6 tool definitions instead of 50-100, saving thousands of tokens per request

What AI frameworks does CodeSpar support?

CodeSpar works with any AI framework through four official adapters, plus a direct HTTP API for any language:

You can also call the HTTP API directly from any language -- Python, Go, Rust, or any HTTP client.

Is CodeSpar open source?

The client-side SDK (@codespar/sdk) and all adapter packages are published on npm and open for inspection. The MCP server infrastructure, routing engine, and API backend are proprietary hosted services. The client libraries are designed to be transparent -- you can read the source to understand exactly what they do.

Can I use CodeSpar without an AI agent?

Yes. The SDK and API work independently of any AI framework. You can call session.execute() directly from your backend code without involving an LLM. This is useful for building traditional backend services that want the routing and provider abstraction benefits without the AI layer.

// No AI agent needed -- direct tool execution
const session = await codespar.sessions.create({ servers: ["stripe"] });
const result = await session.execute({
  name: "codespar_pay",
  arguments: { method: "pix", amount: 5000, currency: "BRL" },
});

Pricing

Is there a free plan?

Yes. The Hobby plan is free forever and includes:

• 20,000 tool calls per month
• Access to all 57 MCP servers and all 6 meta-tools
• 2 API keys
• 60 req/min rate limit
• Community support

No credit card required. Sign up and start building immediately.

What counts as a tool call?

Every invocation of session.execute(), session.send(), or session.sendStream() counts as one tool call. Creating sessions, listing tools, browsing the server catalog, checking usage, and managing API keys do not count. See Billing and Quotas for the full breakdown.

How much does a typical workflow cost?

A standard e-commerce order (discover tools, create checkout, issue invoice, get shipping quote, create label, send confirmation) uses 6 tool calls. At that rate:

What happens when I hit my quota?

At 90% usage, a warning header (X-CodeSpar-Quota-Warning) appears in API responses. At 100%, tool executions return HTTP 429 with a quota_exceeded error. Session creation, tool listing, and server browsing continue to work. Growth plan customers can enable overage billing ($0.20 per 1,000 extra calls) to avoid interruption.

Can I change plans mid-cycle?

Yes. Upgrades take effect immediately with prorated billing -- you pay only for the remaining days at the new rate and your quota increases right away. Downgrades take effect at the end of the current billing cycle; you retain your current quota until then.

Do you offer custom Enterprise pricing?

Yes. If your usage regularly exceeds 2M tool calls per month or you need custom SLAs, dedicated support, or compliance certifications, contact sales@codespar.dev.

Technical

What is a session?

A session is a scoped, authenticated connection to one or more MCP servers. It manages which tools your agent can access, handles server authentication using your stored credentials, and tracks usage for billing. Sessions expire after 30 minutes of inactivity.

What is the difference between execute, send, and sendStream?

All three count as one tool call each.

What is the latency?

Tool call latency depends on the underlying provider API. Typical ranges:

NF-e issuance has the widest range because it communicates with SEFAZ in real time, and SEFAZ response times vary by state and time of day.

Are sandbox responses real?

No. When using a csk_test_ API key, all servers return mock data. No real payments are processed, no real invoices are issued, and no real messages are sent. The mock data is realistic, follows the same JSON schema as production responses, and includes valid-looking IDs, URLs, and timestamps. Use sandbox for development, testing, and demos.

What are meta-tools and why only 6?

Meta-tools are routing abstractions that sit in front of 57 provider-specific servers. Instead of your agent needing to understand each provider's API, it calls one of 6 meta-tools (codespar_discover, codespar_checkout, codespar_pay, codespar_invoice, codespar_ship, codespar_notify), and CodeSpar routes to the appropriate provider.

The constraint to 6 is deliberate: it keeps the LLM's context window small (approximately 1,200 tokens for all tool definitions vs. 10,000-30,000 for raw server tools) and prevents the LLM from being overwhelmed by dozens of similar tools.

Can I access server-specific tools directly?

Yes. In addition to the 6 meta-tools, each connected MCP server exposes its native tools (e.g., stripe_create_subscription, mercadopago_create_preference). These are available through session.tools() and can be called via session.execute(). Use server-specific tools when you need features that meta-tools do not cover.

What happens if a provider is down?

If a provider API is unavailable, CodeSpar returns a 503 error for tool calls that route to that provider. Where possible, CodeSpar falls back to an alternative provider (e.g., if Asaas is down for Pix, it routes to Mercado Pago). Fallback behavior is transparent -- the response includes a provider field so you know which provider handled the call.

Does CodeSpar support webhooks?

Yes. You can configure webhooks in the dashboard to receive notifications when asynchronous events complete -- payment confirmation, invoice authorization, shipping status changes, and message delivery receipts. Webhook payloads include an HMAC signature for verification.

Coverage

Which countries are supported?

CodeSpar focuses on Latin America, with the deepest coverage in Brazil and Mexico:

Brazil has the most complete coverage across all categories. Mexico has strong payment and fiscal support. Other countries are expanding; check the Servers API for the latest catalog.

Which payment providers are supported?

12 payment providers across the region: Stripe, Mercado Pago, Asaas, PagSeguro, Pagarme, Conekta, Inter, Sicredi, and more. Each provider is wrapped as an MCP server with standardized tool definitions. See the full list via GET /v1/servers?category=payments.

Which fiscal systems are supported?

• Brazil: NF-e (goods), NFS-e (services), SPED (tax reporting), CT-e (transport), MDFe (freight manifest)
• Mexico: CFDI (all invoice types: ingreso, egreso, traslado)

All fiscal documents are generated in compliance with the respective tax authority's specifications (SEFAZ for Brazil, SAT for Mexico).

Can I request a new integration?

Yes. Email integrations@codespar.dev with the provider name, country, category, and your use case. Popular requests are prioritized. You can also check the public roadmap to see what integrations are planned.

Security

How are provider credentials stored?

Provider credentials (Stripe keys, OAuth tokens, digital certificates) are encrypted at rest using AES-256 and stored in isolated, access-controlled infrastructure. Credentials are decrypted only in memory at the moment of use and are never returned in API responses. When viewing auth configs in the dashboard, only the last 4 characters are shown.

Does CodeSpar see my customers' data?

CodeSpar processes data in transit to route tool calls to the correct provider. Customer data (names, emails, addresses, payment details) passes through CodeSpar's infrastructure but is not stored beyond what is needed to complete the tool call. Transaction metadata (tool name, timestamp, session ID) is retained for auditing and billing. Data retention follows each provider's policies.

Is CodeSpar SOC 2 compliant?

SOC 2 Type II certification is in progress. Contact security@codespar.dev for our current security documentation, including architecture diagrams, data flow documentation, and penetration test results.

How do I report a security vulnerability?

Email security@codespar.dev with details. We follow responsible disclosure practices and will respond within 24 hours. Do not open public GitHub issues for security vulnerabilities.

What authentication methods are supported?

Two mechanisms:

1. Bearer tokens (csk_live_ / csk_test_) -- Standard API key authentication for application-to-CodeSpar communication. See Authentication.
2. Service keys (cssk_internal_) -- Elevated server-to-server authentication with higher rate limits and cross-organization access. Used for trusted internal infrastructure.

Both key types can be scoped to specific permissions and rotated without downtime.

Open Source

What parts of CodeSpar are open source?

The client-side packages are published on npm and available for inspection:

The backend API, MCP server infrastructure, routing engine, and provider integrations are proprietary hosted services.

Can I self-host CodeSpar?

Not currently. CodeSpar is a hosted service. The complexity of maintaining 57 provider integrations, managing authentication flows, and handling fiscal compliance across multiple countries makes self-hosting impractical. We are evaluating a self-hosted option for Enterprise customers with specific compliance requirements.

How do I contribute?

The client libraries accept contributions. File issues or pull requests on GitHub. For the hosted service, submit feature requests and integration requests through the dashboard or via email.