Providers

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

Every operation below requires a Bearer token. See Authentication.

GET /v1/providers

List the MCP servers this project can attach to a session

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/providers \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

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

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/providers",
    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/providers", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

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

{
  "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/providers/{slug}

Read one provider

The same enriched row the list returns, by slug — {slug} is the catalog primary key, the value GET /v1/providers/{slug}/auth-schema also takes. 404 for another project's generated (gen_-prefixed) provider: the list already hides it, so answering differently here would leak what the list conceals.

Responses

Response 200

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

GET /v1/providers/{slug} HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/providers/{slug}",
    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/providers/{slug}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/providers/{slug}");

{
  "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/providers/{slug}/auth-schema

The connect form for one provider

The form to render so an operator can connect this provider, and never a credential. The vault is write-only from this direction: no submitted value is readable back through any operation in this document.

fields is empty for oauth (the connect flow is a redirect, not a form), for none (there is nothing to hold) and for any provider whose auth mechanism carries no per-field input. An empty array therefore means "no form", not "not configured".

base_url and oauth_authorize_url are resolved for the environment the credential authenticates in, so what is previewed here is the host the call will actually reach.

Requires the servers:read scope.

Path parameters

Responses

Response 200

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

GET /v1/providers/{slug}/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/providers/{slug}/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/providers/{slug}/auth-schema", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/providers/{slug}/auth-schema", {
  path: {
    slug: "example"
  }
});

{
  "server_id": "srv_0000000000000000",
  "auth_type": "api_key",
  "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"
    }
  ]
}

POST /v1/providers/{slug}/verify-connection

Test one provider connection's credential

Issue one known-safe read against the provider with the connection's own stored credential, so an operator learns that a credential does not authenticate here instead of learning it on an agent's first real call.

The check is a read on both of its lanes. A provider with a bespoke recipe gets that recipe's GET; every other provider falls back to re-running the read its own catalog entry declares as its probe, which is the same authenticated read that confirms a freshly provisioned sandbox. Which lane ran is visible in the body: only a recipe extracts an account.

READ THE OUTCOME FROM ok, NOT FROM THE STATUS. Every failure body carries ok: false and a stable error; the status is a mapping from that code and is the less precise of the two. One status in particular carries two different bodies — see the 404.

EXACTLY ONE of the seven failures is a verdict about the credential: provider_rejected. The other six are the absence of a verdict, and they are not interchangeable with a bad credential. redirect_not_followed is the subtle one: the configured host answered by pointing somewhere else, the probe deliberately does not follow it, and so no answer about the credential was obtained from anyone.

Requires the connections:write scope. It is the scope the connection family carries, and it is wider than this operation needs: nothing in this project is written by asking a provider to judge a credential.

Path parameters

Responses

Response 200

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

POST /v1/providers/{slug}/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/providers/{slug}/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/providers/{slug}/verify-connection", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.post("/v1/providers/{slug}/verify-connection", {
  path: {
    slug: "example"
  }
});

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