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

Servers API

The Servers API lets you browse CodeSpar's catalog of 57 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`, `oauth`, `basic`, `certificate`
`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": 57,
  "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": "certificate",
      "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

Returns detailed information about a specific server, including its full tool list with input schemas.

Auth required: Yes (scope: servers:read)

curl example

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

Response -- `200 OK`

{
  "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",
  "docs_url": "https://stripe.com/docs",
  "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 6 meta-tools are always available regardless of which servers are connected.

Server categories

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

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
`oauth`	OAuth 2.0 flow for user-level access	Mercado Pago, Nuvemshop
`basic`	HTTP Basic Auth (username + password/token)	Jadlog, some ERPs
`certificate`	mTLS certificate-based auth	Banking APIs, SEFAZ (NF-e)

Rate limits

The Servers API has its own rate limits, separate from session operations:

Plan	Rate limit
Hobby	30 req/min
Starter	120 req/min
Growth	600 req/min

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

Sessions API -- Create sessions with these servers
Tools and Meta-Tools -- How meta-tools route to servers
Authentication -- Configuring server credentials
Glossary -- Definitions for MCP, server, provider, and other terms

Servers API

On this page