Servers

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

Every operation below requires a Bearer token. See Authentication.

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

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": "mercado-pago",
      "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/mercado-pago.svg"
    }
  ],
  "total": 114,
  "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": "mercado-pago",
      "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/mercado-pago.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 categories

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

Server status values

Authentication types

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

Rate limits

The catalog reads on this page (GET /v1/servers, /v1/servers/:id/tools, /v1/servers/:id/auth-schema) carry no rate limit of their own. The limiter that exists applies to tool execution, and it is not tiered by plan.

It is a token bucket keyed by (account, server) — so the budget is per upstream provider, not per API key and not per plan. The default bucket is a capacity of 60 with 1 token/second of refill; a few providers that publish generous ceilings get more (Stripe 300 / 25 per second, Asaas 120 / 10 per second). Buckets are held in the API process, so a multi-replica deployment gives each replica its own.

Exceeding it answers 429 with a Retry-After header in seconds and retry_after_ms in the body:

{
  "error": "rate_limited",
  "server": "asaas",
  "retry_after_ms": 1400,
  "message": "Rate limit reached for server \"asaas\". Retry in ~2s."
}

There are no X-RateLimit-Limit / -Remaining / -Reset headers. Read Retry-After and back off with jitter.

Rate limits are not billing — see Billing for the pricing model.

Error responses

429 rate_limited does not appear on these three endpoints — it belongs to tool execution, on POST /v1/sessions/:id/tool-calls.

Next steps

Every operation, from the spec

Generated from the published OpenAPI document, so it never drifts from what the API actually serves. The section above is written by hand and carries what a schema cannot: the object model, field rules, and the order to call things in.

GET /v1/servers

List the MCP servers this project can attach to a session

DEPRECATED alias of GET /v1/providers (ent#979), kept for two releases. Same handler, same required scope; switch the path and nothing else changes.

The catalog POST /v1/sessions draws its servers ids from. total is everything visible to this project, filtered is what survived the query parameters, and servers is the filtered page; the route does not paginate, so filtered and servers.length agree.

Visibility is per project: another project's generated (gen_-prefixed) servers are absent, global catalog rows always present. Presence here is NOT permission to invoke — that is gated separately on a connected account, which is what POST /v1/connect/start establishes.

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/servers \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/servers HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/servers",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/servers", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/servers");

{
  "total": 0,
  "filtered": 0,
  "servers": [
    {
      "id": "servercatalogrow_0000000000000000",
      "name": "Example",
      "pkg": "string",
      "category": "string",
      "country": "string",
      "auth_type": "string",
      "tools_count": 1,
      "description": "string",
      "status": "string",
      "provider_homepage": "string",
      "provider_logo_url": "https://example.com/hook",
      "provider_logo_fallback_url": "https://example.com/hook",
      "provider_docs_url": "https://example.com/hook",
      "sandbox_available": true,
      "sandbox_url": "https://example.com/hook",
      "description_pt_br": "string",
      "subaccount_provisionable": true,
      "engine_provisionable": true,
      "engine_status": "none",
      "connect_fields": 0,
      "connectable": true
    }
  ]
}

GET /v1/servers/{id}/auth-schema

Read the credential form a provider needs, without reading any credential

What to ask an operator for before connecting this provider, and where the request will go once connected. It NEVER returns a stored secret: the vault is write-only from this side, and fields describes inputs to collect, not values that exist.

AN EMPTY fields DOES NOT MEAN NOTHING TO DO. oauth collects nothing here because the browser leg starts at POST /v1/connections/start instead, and none needs no credential. Every other type returns one field per catalog-declared ref, which is exactly the key set POST /v1/connections validates the secret object against: jwt_ecdsa asks for the CDP API key name and its private key, cdp for the CDP API key id, API key secret and wallet secret. Both CDP forms are served only where the deployment enables CDP self-serve connect (CDP_SELF_SERVE_CONNECT, off by default); otherwise they come back empty. A form type whose catalog row declares no refs comes back empty and cannot be connected; connectable on GET /v1/servers already says so per row.

base_url IS ENVIRONMENT-RESOLVED against the credential in hand: a test key sees the provider's test host when the catalog declares one, and the live host otherwise. It is the empty string when the provider has no endpoint row, which is a catalog gap rather than a value to dial.

This is the path that shipped first; GET /v1/providers/{slug}/auth-schema is the same handler at the canonical path (ent#979) and is not yet described in this document, so the full response is described HERE and nothing is withheld until you switch paths.

The visibility gate in front of this operation only hides GENERATED providers (ids prefixed gen_) that belong to another project. Any id without that prefix passes the gate, including an id that names no provider at all. Past the gate, a provider that is genuinely absent from the catalog is a 404 as well, so this operation does distinguish a real provider from an invented one.

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/servers/{id}/auth-schema \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/servers/{id}/auth-schema HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/servers/{id}/auth-schema",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/servers/{id}/auth-schema", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/servers/{id}/auth-schema", {
  path: {
    id: "srv_0000000000000000"
  }
});

{
  "server_id": "srv_0000000000000000",
  "auth_type": "string",
  "environment": "live",
  "base_url": "https://example.com/hook",
  "oauth_authorize_url": "https://example.com/hook",
  "fields": [
    {
      "name": "Example",
      "kind": "api_key",
      "label": "Example",
      "header_name": "Example"
    }
  ]
}

GET /v1/servers/{id}/tools

List the tools a provider exposes

Every tool registered for this provider, ordered by name, with no limit and no cursor: total is the length of tools and the two cannot disagree.

AN UNKNOWN PROVIDER IS 200 HERE, NOT 404, and it is the one thing worth knowing about this operation. The visibility gate in front of this operation only hides GENERATED providers (ids prefixed gen_) that belong to another project. Any id without that prefix passes the gate, including an id that names no provider at all. There is no second check after it, so an id that names nothing reaches the tool query, matches no rows, and comes back as a well-formed empty list with that id echoed in server_id. An empty tools therefore means either a real provider with nothing registered or a provider that does not exist, and this response cannot tell you which. The 404 below is reachable only for another project's generated provider.

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/servers/{id}/tools \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/servers/{id}/tools HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/servers/{id}/tools",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/servers/{id}/tools", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/servers/{id}/tools", {
  path: {
    id: "srv_0000000000000000"
  }
});

{
  "server_id": "srv_0000000000000000",
  "total": 0,
  "tools": [
    {
      "name": "Example",
      "description": "string"
    }
  ]
}

POST /v1/servers/{id}/verify-connection

Ask the provider whether this project's stored credential still works

Issues ONE safe read against the provider using the credential this project has stored for it, and reports what came back. POST because it leaves the process and spends a provider call, not because it changes anything here: no state of yours is altered by it. It takes NO REQUEST BODY, and anything sent is ignored.

WHICH READ depends on the provider. A handful ship a bespoke recipe, and those are the ones that can return an account summary. Everything else re-runs the provider's declared functional probe, the same authenticated read used to confirm a sandbox works when it is first set up; that path returns no account. A provider with neither answers 501.

READ THE STATUS, NOT THE BODY, TO DECIDE WHAT TO DO. Seven failure codes map onto seven distinct statuses, and only ONE of them is worth retrying unchanged (502). 401 is a verdict on the credential; 424 means there is no connection to test yet; 409 means the host redirected and never judged the credential, so a retry gets the same non-answer; 501 and 503 are configuration, not weather.

THE 502 IS WIDER THAN ITS NAME. provider_unreachable is what every non-2xx that is not a redirect and not a 401 or 403 becomes, so a provider answering 400, 404, 409, 422 or 429 arrives here as 502 with the provider's own status in status. An agent that retries every 502 will retry a 429 sensibly and a 400 forever. Read status before deciding.

TWO DIFFERENT BODIES SHARE THE 404, from two different lines: the visibility gate's { error, server_id }, and the verify outcome's { ok: false, provider, error } when the credential resolver finds no such provider in the catalog. Both are described below.

This is the path that shipped first; POST /v1/providers/{slug}/verify-connection is the same handler at the canonical path (ent#979) and is not yet described in this document.

The visibility gate in front of this operation only hides GENERATED providers (ids prefixed gen_) that belong to another project. Any id without that prefix passes the gate, including an id that names no provider at all.

Path parameters

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/servers/{id}/verify-connection \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

POST /v1/servers/{id}/verify-connection HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/servers/{id}/verify-connection",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/servers/{id}/verify-connection", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/servers/{id}/verify-connection", {
  path: {
    id: "srv_0000000000000000"
  }
});
// r.status is one of the documented statuses (200, 403, 422),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "ok": true,
  "provider": "string",
  "account": {
    "id": "obj_0000000000000000",
    "name": "Example",
    "extras": {}
  },
  "latency_ms": 0
}