HTTP API reference for browsing and filtering CodeSpar's catalog of MCP servers across payments, fiscal, logistics, messaging, banking, ERP, and crypto.

Servers API

The Servers API lets you browse CodeSpar's catalog of MCP servers. Each server represents an integration with a commerce provider -- a payment gateway, shipping carrier, fiscal authority, messaging platform, banking API, ERP system, or crypto exchange.

Use the Servers API to understand what integrations are available, discover capabilities before creating sessions, and build dynamic UIs that show users which providers they can connect.

Base URL: https://api.codespar.dev

All endpoints require authentication via Bearer token. See Authentication.

GET /v1/servers

Returns the server catalog with filtering and search capabilities. Results are paginated.

Auth required: Yes (scope: servers:read)

Query parameters

Parameter	Type	Default	Description
`category`	`string`	--	Filter by category: `payments`, `fiscal`, `logistics`, `messaging`, `banking`, `erp`, `crypto`
`country`	`string`	--	Filter by country code (ISO 3166-1 alpha-2): `BR`, `MX`, `AR`, `CO`, `CL`
`q`	`string`	--	Full-text search across server name, description, and capabilities
`status`	`string`	--	Filter by status: `stable`, `beta`, `alpha`, `deprecated`
`auth_type`	`string`	--	Filter by auth type: `api_key`, `path_secret`, `oauth`, `cert`, `hmac_signed`, `none`
`limit`	`number`	`50`	Results per page (max 100)
`offset`	`number`	`0`	Pagination offset

Response schema

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "category": "string",
      "countries": ["string"],
      "capabilities": ["string"],
      "auth_type": "string",
      "status": "string",
      "tools_count": "number",
      "icon_url": "string"
    }
  ],
  "total": "number",
  "limit": "number",
  "offset": "number"
}

Example: list all servers

curl "https://api.codespar.dev/v1/servers" \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- 200 OK:

{
  "data": [
    {
      "id": "stripe",
      "name": "Stripe",
      "description": "Global payment processing platform. Supports cards, Pix, boleto, and 135+ currencies.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["checkout", "subscriptions", "refunds", "pix", "boleto", "cards"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 12,
      "icon_url": "https://codespar.dev/icons/stripe.svg"
    },
    {
      "id": "mercadopago",
      "name": "Mercado Pago",
      "description": "Latin America's leading payment platform. Native Pix, boleto, and Mercado Credito.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["pix", "boleto", "checkout", "wallet", "installments"],
      "auth_type": "oauth",
      "status": "stable",
      "tools_count": 15,
      "icon_url": "https://codespar.dev/icons/mercadopago.svg"
    }
  ],
  "total": 112,
  "limit": 50,
  "offset": 0
}

Example: filter by category

Retrieve only payment servers:

curl "https://api.codespar.dev/v1/servers?category=payments" \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- 200 OK:

{
  "data": [
    {
      "id": "stripe",
      "name": "Stripe",
      "description": "Global payment processing platform. Supports cards, Pix, boleto, and 135+ currencies.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["checkout", "subscriptions", "refunds", "pix", "boleto", "cards"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 12,
      "icon_url": "https://codespar.dev/icons/stripe.svg"
    },
    {
      "id": "asaas",
      "name": "Asaas",
      "description": "Brazilian payment platform specializing in Pix, boleto, and recurring billing.",
      "category": "payments",
      "countries": ["BR"],
      "capabilities": ["pix", "boleto", "subscriptions", "split_payments"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 10,
      "icon_url": "https://codespar.dev/icons/asaas.svg"
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Example: filter by country

Retrieve servers available in Mexico:

curl "https://api.codespar.dev/v1/servers?country=MX" \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- 200 OK:

{
  "data": [
    {
      "id": "stripe",
      "name": "Stripe",
      "description": "Global payment processing platform. Supports cards, Pix, boleto, and 135+ currencies.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["checkout", "subscriptions", "refunds", "pix", "boleto", "cards"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 12,
      "icon_url": "https://codespar.dev/icons/stripe.svg"
    },
    {
      "id": "conekta",
      "name": "Conekta",
      "description": "Mexican payment platform. Native SPEI, OXXO cash payments, and card processing.",
      "category": "payments",
      "countries": ["MX"],
      "capabilities": ["spei", "oxxo", "cards", "checkout"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 8,
      "icon_url": "https://codespar.dev/icons/conekta.svg"
    },
    {
      "id": "cfdi",
      "name": "CFDI",
      "description": "Mexican fiscal document generation (Comprobante Fiscal Digital por Internet) via SAT.",
      "category": "fiscal",
      "countries": ["MX"],
      "capabilities": ["cfdi_ingreso", "cfdi_egreso", "cfdi_traslado", "cancelation"],
      "auth_type": "cert",
      "status": "stable",
      "tools_count": 6,
      "icon_url": "https://codespar.dev/icons/cfdi.svg"
    }
  ],
  "total": 18,
  "limit": 50,
  "offset": 0
}

Example: full-text search

Search for servers that support Pix:

curl "https://api.codespar.dev/v1/servers?q=pix" \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- 200 OK:

{
  "data": [
    {
      "id": "stripe",
      "name": "Stripe",
      "description": "Global payment processing platform. Supports cards, Pix, boleto, and 135+ currencies.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["checkout", "subscriptions", "refunds", "pix", "boleto", "cards"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 12,
      "icon_url": "https://codespar.dev/icons/stripe.svg"
    },
    {
      "id": "mercadopago",
      "name": "Mercado Pago",
      "description": "Latin America's leading payment platform. Native Pix, boleto, and Mercado Credito.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["pix", "boleto", "checkout", "wallet", "installments"],
      "auth_type": "oauth",
      "status": "stable",
      "tools_count": 15,
      "icon_url": "https://codespar.dev/icons/mercadopago.svg"
    },
    {
      "id": "asaas",
      "name": "Asaas",
      "description": "Brazilian payment platform specializing in Pix, boleto, and recurring billing.",
      "category": "payments",
      "countries": ["BR"],
      "capabilities": ["pix", "boleto", "subscriptions", "split_payments"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 10,
      "icon_url": "https://codespar.dev/icons/asaas.svg"
    }
  ],
  "total": 5,
  "limit": 50,
  "offset": 0
}

Example: combine filters

Retrieve stable payment servers in Brazil:

curl "https://api.codespar.dev/v1/servers?category=payments&country=BR&status=stable" \
  -H "Authorization: Bearer csk_live_abc123..."

GET /v1/servers/:id/tools

Returns a server's tool list with input schemas. (There is no standalone GET /v1/servers/:id: server metadata comes from the list endpoint's rows; this endpoint serves the tools; GET /v1/servers/:id/auth-schema serves the credential shape the connect flow needs.)

Auth required: Yes (scope: servers:read)

curl example

curl https://api.codespar.dev/v1/servers/stripe/tools \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- `200 OK`

{
  "tools": [
    {
      "name": "stripe_create_checkout_session",
      "description": "Create a Stripe Checkout session with a payment link",
      "input_schema": {
        "type": "object",
        "properties": {
          "line_items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "price_data": {
                  "type": "object",
                  "properties": {
                    "currency": { "type": "string" },
                    "product_data": {
                      "type": "object",
                      "properties": {
                        "name": { "type": "string" }
                      }
                    },
                    "unit_amount": { "type": "number" }
                  }
                },
                "quantity": { "type": "number" }
              }
            }
          },
          "mode": {
            "type": "string",
            "enum": ["payment", "subscription", "setup"]
          },
          "success_url": { "type": "string" },
          "cancel_url": { "type": "string" }
        },
        "required": ["line_items", "mode"]
      }
    },
    {
      "name": "stripe_create_refund",
      "description": "Refund a Stripe payment",
      "input_schema": {
        "type": "object",
        "properties": {
          "payment_intent": { "type": "string", "description": "ID of the PaymentIntent to refund" },
          "amount": { "type": "number", "description": "Amount to refund in cents (partial refund). Omit for full refund." },
          "reason": { "type": "string", "enum": ["duplicate", "fraudulent", "requested_by_customer"] }
        },
        "required": ["payment_intent"]
      }
    }
  ]
}

Server-specific tools (like stripe_create_checkout_session) are only available in sessions that connect to that server. The 14 meta-tools are always available regardless of which servers are connected.

Server categories

Category	Examples
`payments`	Stripe, Mercado Pago, Asaas, PagSeguro, Pagarme, Conekta, Inter, Sicredi
`fiscal`	NF-e, NFS-e, SPED, CT-e, MDFe, CFDI
`logistics`	Correios, Jadlog, Loggi, Mercado Envios, Total Express, DHL, Estafeta
`messaging`	Twilio, WhatsApp Business, SendGrid, Mailgun, Amazon SNS
`banking`	Inter, Itau, Bradesco, Banco do Brasil, Sicoob, Nubank
`erp`	Bling, Tiny, Omie, TOTVS, ContaAzul, Nuvemshop
`crypto`	Mercado Bitcoin, Foxbit, Binance Pay, Coinbase Commerce

Per-category counts change as the catalog grows; query GET /v1/servers?category=<name> for live numbers.

Server status values

Status	Description	Recommendation
`stable`	Production-ready, fully tested, SLA-backed	Safe for production use
`beta`	Functional but may have breaking changes in minor versions	Safe for staging; pin the server version in production
`alpha`	Experimental, limited support, may be removed	Development and testing only
`deprecated`	Scheduled for removal; an alternative is available	Migrate to the suggested replacement

Authentication types

Each server requires one of these authentication methods, configured in the Auth Configs section of the dashboard:

Auth type	Description	Examples
`api_key`	Authenticate with a secret key from the provider	Stripe, Asaas, SendGrid
`path_secret`	Secrets embedded in URL path plus optional companion header	Z-API, Take Blip, Evolution API
`oauth`	OAuth 2.0 flow for user-level access	Mercado Pago, Melhor Envio
`cert`	mTLS with X.509 client certificate (PEM)	Banco do Brasil, Itaú, Bradesco, Santander, Caixa, Sicoob, Sicredi, C6, Original
`hmac_signed`	Per-request HMAC signature over `timestamp + method + path + body`	Foxbit
`jwt_ecdsa`	Per-request ES256 JWT signed with an ECDSA P-256 private key	Coinbase Developer Platform
`two_header`	Two co-equal credential headers, no Authorization Bearer	Cielo, Transbank, Kushki, Payway
`none`	No credentials required	Brasil API

Rate limits

The Servers API has its own rate limits, separate from session operations. Rate limits protect the managed runtime from abuse; they are not billing — see Billing for the per-settled-transaction pricing model.

Tier	Rate limit
Open Source (self-hosted)	N/A — you host it
Orchestration	300 req/min
Enterprise	1,200 req/min (bespoke ceilings available)

Rate limit headers are included in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1713178260

Error responses

Status	Error code	Description
`400`	`invalid_request`	Invalid query parameter value
`401`	`unauthorized`	Invalid or missing API key
`404`	`not_found`	Server ID does not exist in the catalog
`429`	`rate_limited`	Too many requests; check `Retry-After` header

Next steps

REFERENCE

Sessions API

Create sessions against these servers and execute tool calls.

CONCEPT

Tools & Meta-Tools

How the 14 meta-tools route to specific servers by domain.

CONCEPT

Authentication

Configure provider credentials in the dashboard auth vault.

GLOSSARY

Glossary

Definitions for MCP, server, provider, BACR, and more.

Servers API

On this page