Glossary

A reference of terms used throughout the CodeSpar documentation. Entries are organized alphabetically.

---

Adapter

A package that converts CodeSpar session tools into the format expected by a specific AI framework. Adapters handle the translation between CodeSpar's MCP-based tool format and the framework's native tool/function calling interface.

Available adapters: @codespar/claude (Anthropic SDK), @codespar/openai (OpenAI SDK), @codespar/vercel (Vercel AI SDK), @codespar/mcp (Claude Desktop, Cursor, any MCP client).

API Key

A secret token used to authenticate your application to the CodeSpar API. Keys use the prefix csk_live_ for production and csk_test_ for sandbox environments. Each key can be scoped to specific permissions (e.g., sessions:create, tools:execute). See Authentication.

BACR

Build-Act-Confirm-Report. The internal execution pattern that CodeSpar follows when processing a tool call. The system builds the request in the provider's native format, acts on the provider API, confirms the result matches expectations, and reports back to the calling agent. As a developer, you do not interact with BACR directly -- it is the engine behind session.execute() that ensures reliability and consistency across 57 providers.

Bearer Token

An HTTP authentication scheme where the API key is passed in the Authorization header as Bearer <key>. All requests to api.codespar.dev must include a bearer token. Example: Authorization: Bearer csk_live_abc123.... See Authentication.

Budget Policy

A governance rule that limits how much an AI agent can spend through CodeSpar in a given time period. Budget policies can be set per agent, per session, or per organization. When a budget limit is reached, tool calls that would result in financial transactions are blocked. Budget policies are configured in the dashboard under Settings > Policies.

CFDI

Comprobante Fiscal Digital por Internet. Mexico's mandatory electronic invoice format, regulated by SAT (Servicio de Administracion Tributaria). CodeSpar's fiscal servers automate CFDI generation through the codespar_invoice meta-tool with type: "cfdi". CFDI documents must include a digital seal (sello digital) and be reported to SAT.

Commercial Memory

A persistent data store that tracks an AI agent's past commerce interactions -- previous orders, customer preferences, payment methods used, shipping addresses, and preferred carriers. Commercial memory enables agents to provide personalized recommendations and avoid asking for information the customer has already provided. Stored per-organization, encrypted at rest.

Complete Loop

The recommended pattern for agent-commerce interactions: Discover available tools, Execute the appropriate action, Confirm the result. CodeSpar's session.loop() method encapsulates this pattern, allowing agents to describe intent in natural language and have CodeSpar handle tool selection, sequencing, and error recovery. See Sessions.

MCP

Model Context Protocol. An open standard created by Anthropic for connecting AI models to external tools and data sources. CodeSpar wraps 57 commerce APIs as MCP servers, making them accessible to any MCP-compatible client (Claude Desktop, Cursor, custom agents built with any framework). MCP defines the wire format for tool definitions (input_schema) and tool results. Learn more about MCP.

MCP Server

A service that exposes tools and resources following the Model Context Protocol specification. In CodeSpar, each commerce provider (Stripe, Mercado Pago, Correios, NF-e, etc.) is wrapped as an MCP server with standardized tool definitions. Servers are connected to sessions to make their tools available to your agent. Browse the full catalog via the Servers API.

Meta-tool

One of CodeSpar's 6 high-level routing tools: codespar_discover, codespar_checkout, codespar_pay, codespar_invoice, codespar_ship, and codespar_notify. Meta-tools abstract away provider-specific details and route calls to the appropriate MCP server based on the arguments (payment method, currency, region). This reduces the number of tools in the LLM's context window from 50-100 to 6. See Tools and Meta-Tools.

NF-e (Nota Fiscal Eletronica)

Brazil's electronic invoice for goods, required by law for most commercial transactions involving physical products. NF-e documents are transmitted to SEFAZ for authorization and include a 44-digit access key for verification. CodeSpar's fiscal MCP servers automate NF-e issuance through the codespar_invoice meta-tool with type: "nfe".

NFS-e (Nota Fiscal de Servicos Eletronica)

Brazil's electronic invoice for services. Unlike NF-e (which covers goods), NFS-e is regulated at the municipal level, meaning each city has its own rules and systems. CodeSpar normalizes this complexity behind the codespar_invoice meta-tool with type: "nfse".

Pix

Brazil's instant payment system operated by the Central Bank (Banco Central do Brasil). Pix transfers settle in seconds, operate 24/7/365, and are free for individuals. Several CodeSpar payment servers support Pix, including Stripe, Mercado Pago, Asaas, and PagSeguro. When processing a Pix payment through codespar_pay, CodeSpar returns a Pix copy-paste code and a QR code URL.

Preset

A named shortcut for a common combination of MCP servers. Instead of listing servers individually when creating a session, you can pass a preset name (e.g., "payments", "brazilian", "ecommerce"). Presets can be combined with explicit servers arrays. See Sessions.

Provider

A third-party commerce service -- payment gateway, shipping carrier, fiscal authority, messaging platform, banking API, ERP, or crypto exchange -- that CodeSpar integrates with. Each provider is wrapped as an MCP server. Examples: Stripe, Mercado Pago, Correios, Twilio, SEFAZ.

Sandbox

A testing environment accessed with csk_test_ API keys. Sandbox sessions connect to mock servers that return realistic simulated data without processing real transactions, issuing real invoices, or sending real messages. The mock data follows the same schema as production responses. Also refers to the interactive sandbox in the dashboard for experimenting with tool calls.

SEFAZ

Secretaria da Fazenda. The state-level tax authority in Brazil responsible for authorizing fiscal documents like NF-e. Each of Brazil's 27 states operates its own SEFAZ instance. CodeSpar's fiscal servers communicate with SEFAZ in real time to authorize, cancel, and query NF-e documents.

Service Auth

A secondary authentication mechanism using the x-codespar-service-key header, designed for trusted server-to-server communication. Service keys (cssk_internal_) have elevated permissions, bypass rate limits, and can access sessions across an entire organization. See Authentication.

Session

A scoped, authenticated connection to one or more MCP servers. Sessions manage which tools your agent can access, handle server authentication via stored credentials, and track usage for billing. Sessions expire after 30 minutes of inactivity. Created via the SDK (codespar.sessions.create()) or the Sessions API. See Sessions.

SPEI

Sistema de Pagos Electronicos Interbancarios. Mexico's electronic interbank payment system, analogous to Brazil's Pix. SPEI transfers settle within seconds during banking hours and are widely used for e-commerce payments. Supported through CodeSpar's Mexican payment servers (Conekta, Stripe).

Tool

A function exposed by an MCP server that an AI agent can call. Each tool has a name (e.g., codespar_pay), a description (natural language for the LLM), and an input_schema (JSON Schema defining the parameters). Tools are accessed through sessions.

Tool Call

A single invocation of a tool through a session. Tool calls are the billing unit in CodeSpar -- each session.execute(), session.send(), or session.sendStream() counts as one tool call. See Billing and Quotas.

Trigger

A webhook-based automation that fires when a specific event occurs in a connected provider. For example, a trigger can notify your agent when a Pix payment is confirmed or when a shipping status changes. Triggers are configured via the Triggers API and deliver events to a webhook URL you specify.

Trust Graph

A data structure that maps trust relationships between AI agents and commerce providers. The trust graph tracks which agents have been authorized to perform which operations (e.g., "Agent X can process payments up to R$500 via Stripe but cannot issue refunds"). Trust graphs are managed per-organization and enforced at the session level.

Webhook

An HTTP callback sent by CodeSpar to your application when an asynchronous event completes. Common webhook events include payment confirmation, invoice authorization, shipping status updates, and message delivery receipts. Webhooks are configured in the dashboard under Settings > Webhooks and include an HMAC signature for verification.