List connectors | CoreSpeed

GEThttps://api.corespeed.io/connectors

Authorizations

Authorizationstringheaderrequired: Bearer <sk-cs-…> — a CoreSpeed API key, or a user session JWT. x-api-key: <sk-cs-…> is accepted in its place.

The array holds two entry variants, discriminated by the presence of kind:

OAuth connector — no kind field. Carries auth and a real icon_url.
Remote MCP connector — kind: "remote-mcp", an org-registered upstream MCP server. Carries a remote block, no auth, icon_url: null, and always an empty accounts array.

A client that requires auth or a non-null icon_url will reject valid remote entries. Branch on kind first.

Shared fields

idstringrequired

Connector id (a slug for remote entries), and the prefix of its tool names (notion__create_page; remote tools carry the org marker on top: org__<slug>__<tool>).

kind"remote-mcp"optional

Present only on org-registered remote MCP connectors. Absent on OAuth connectors — that absence is the discriminator.

categorystringoptional

What the connector is for, from a closed vocabulary: "communication", "business", "knowledge", "productivity", "creative", "developer". Group or filter the catalog by it rather than by name.

Absent on remote entries — the platform cannot know what an org-registered upstream fronts, so it publishes no guess. Treat a missing category as uncategorized; do not substitute a default.

(Until 2026-08-21 this was the constant "connector" on both variants.)

namestringrequired

Display name as the provider brands it, or the registered display name.

descriptionstringrequired

What the connector's tools can do. On remote entries this is generated and marks the upstream as self-described and unverified.

urlstringrequired

The connector's own resource URL on this host.

mcp_urlstringrequired

Always the unified POST /mcp endpoint. Per-connector MCP URLs are retired and return 404.

statusstringrequired

"connected" | "needs_reauth" | "disconnected" for this caller.

icon_urlstring | nullrequired

Icon URL. The field is icon_url — not icon — and it is null on remote entries.

accountsarrayrequired

Connected accounts visible to this caller. Empty when disconnected, and always empty on remote entries.

OAuth connector only

authobjectrequired: Grant metadata. auth.type is "oauth2" (see the four shapes below), "oauth1a" (Trello and Zotero — an OAuth 1.0a ceremony with the same fields as the upstream-console shape), or "api_key" — an api-key connector is connected by pasting a key in the dashboard, its scopes is always empty, and it never carries a credential_source block. Any curated entry may additionally carry auth.api_key_connect: true (this environment accepts pasted keys for it — on an oauth2 connector that is a second connect door) and auth.api_key_probe (false = the paste is stored unverified with a fingerprint identity); OAuth-typed entries may carry auth.oauth_configured (false = no OAuth app can serve a connect — treat the key door as the only method); accounts then carry auth_kind ("oauth2" | "api_key") naming the door that created them, and key accounts carry key_verified (false = stored without a vendor check). Never present on remote entries.

Remote MCP connector only

remote.upstream_urlstringrequired: The registered upstream MCP server URL.
remote.auth_modestringrequired: How CoreSpeed authenticates to the upstream. "none" additionally carries a remote.warning.
remote.tool_countnumber | nullrequired: Tools in the last snapshot, or null until the first successful snapshot — a registration is kept when its initial snapshot fails or while OAuth authorization is still pending. The single-connector read (GET /connectors/:id) also returns remote.tools. Those are CoreSpeed snapshot records, not upstream MCP Tool objects: each carries the sanitized published name, the original_name it maps back to, a snake-case input_schema, and a schema_hash. A client reading inputSchema off these will find nothing.
remote.snapshot_fetched_atstring | nullrequired: When that snapshot was taken, null in the same no-snapshot case. So is remote.full_schema_hash — a bare SHA-256 as 64 lowercase hex characters, with no sha256: prefix to strip. Treat all three as one signal: null means "this upstream has never answered yet", not "no tools". remote.created_by_user_id and remote.created_at are always present.
credential_sourceobjectoptional: Curated OAuth entries only (never on auth.type: "api_key" connectors — a pasted key rides no app): which OAuth app carries this connector's authorizations for your workspace. active is "platform" (CoreSpeed's app), "org" (your workspace's own app), or "none" (the org mechanism is open but nothing is configured yet — connect is unavailable until a workspace admin sets it up). org_clients_enabled says whether your workspace may bring its own app. Workspace admins additionally receive an org block (client_id, set_by, created_at, rotated_at, and — on the single-connector read — connections). Absent on older deployments; treat absence as platform-served.
remote.oauthobjectoptional: Present when the upstream uses OAuth: client_source ("dcr" or "preregistered"), issuer, sometimes client_id, and scopes — the scope list the authorize redirect will request, discovered from the upstream at registration. scopes: [] means the upstream published none: authorization is still valid, no scope parameter is sent, and the server applies its default grant.

Account fields

accounts[].idstringrequired: Stable account id.
accounts[].aliasstringrequired: Human-chosen label. Use the alias to select an account instead of putting a provider account id or token into a prompt.
accounts[].identitystringrequired: How the provider identifies the account (handle, workspace, mailbox).
accounts[].scopestringrequired: "private" (owned by one member) or "shared" (available inside the organization).
accounts[].statusstringrequired: "connected" or "needs_reauth". A needs_reauth account still contributes tools, and those calls fail until it is reauthorized.
accounts[].can_removebooleanrequired: Whether this caller may remove the account. Private accounts: the owning member only. Shared accounts: the creator or an organization admin.

The four grant shapes

auth.scopesstring[]required: Required request-time grants, described by scope_descriptions (same keys).
auth.optional_scopesstring[]optional: Provider-optional grants, described by optional_scope_descriptions. An unavailable optional grant does not block the connection.
auth.user_scopesstring[]optional: Grants issued to a separate authorizing-user token — tools that act with the connecting user's own identity — described by user_scope_descriptions.
auth.access_summarystringoptional: Used when the provider fixes access in its app registration instead of accepting meaningful request scopes. Then scopes is empty. Mutually exclusive with request scopes.

curl https://api.corespeed.io/connectors \
  -H "Authorization: Bearer $CORESPEED_API_KEY"

const res = await fetch("https://api.corespeed.io/connectors", {
  headers: { Authorization: `Bearer ${process.env.CORESPEED_API_KEY}` },
});

const { connectors } = await res.json();
for (const connector of connectors) {
  console.log(connector.id, connector.status, connector.accounts.length);
}

import os
import httpx

res = httpx.get(
    "https://api.corespeed.io/connectors",
    headers={"Authorization": f"Bearer {os.environ['CORESPEED_API_KEY']}"},
)

for connector in res.json()["connectors"]:
    print(connector["id"], connector["status"], len(connector["accounts"]))

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.corespeed.io/connectors", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CORESPEED_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Connectors []struct {
			ID       string `json:"id"`
			Status   string `json:"status"`
			Accounts []struct {
				Alias string `json:"alias"`
			} `json:"accounts"`
		} `json:"connectors"`
	}
	json.NewDecoder(res.Body).Decode(&out)
	for _, c := range out.Connectors {
		fmt.Println(c.ID, c.Status, len(c.Accounts))
	}
}

OAuth connector entry

{
  "connectors": [
    {
      "id": "notion",
      "category": "knowledge",
      "name": "Notion",
      "description": "Read and write pages and databases in a Notion workspace.",
      "auth": {
        "type": "oauth2",
        "scopes": [],
        "access_summary": "Read & write pages and databases shared with this Notion connection, including their accessible children."
      },
      "url": "https://api.corespeed.io/connectors/notion",
      "mcp_url": "https://api.corespeed.io/mcp",
      "icon_url": "https://api.corespeed.io/icons/notion.svg",
      "status": "connected",
      "accounts": [
        {
          "id": "acct_01J…",
          "alias": "product-wiki",
          "identity": "Acme workspace",
          "scope": "private",
          "status": "connected",
          "can_remove": true
        }
      ]
    }
  ]
}

kind: "remote-mcp" — no auth, icon_url: null, accounts empty, and a remote block instead. Remote entries share the one connectors array with OAuth entries; the top-level shape never changes.

{
  "connectors": [
    {
      "id": "acme-internal",
      "kind": "remote-mcp",
      "name": "Acme internal tools",
      "description": "Org-registered remote MCP server at mcp.acme.internal (upstream self-described, unverified).",
      "url": "https://api.corespeed.io/connectors/org/acme-internal",
      "mcp_url": "https://api.corespeed.io/mcp",
      "icon_url": null,
      "status": "connected",
      "accounts": [],
      "remote": {
        "upstream_url": "https://mcp.acme.internal/mcp",
        "auth_mode": "oauth",
        "oauth": {
          "client_source": "dcr",
          "issuer": "https://auth.acme.internal",
          "scopes": ["mcp.read", "mcp.write"]
        },
        "tool_count": 12,
        "snapshot_fetched_at": "2026-07-24T09:12:04Z",
        "full_schema_hash": "9f2c1ab4e7d05836bc41f0a29d7e655813cf84a0b2e7d691c5038af74be2019d",
        "created_by_user_id": "user_01J…",
        "created_at": "2026-07-02T18:40:11Z"
      }
    }
  ]
}

No meaningful request scopes: scopes is empty and access_summary describes the access the provider's app registration grants.

{
  "auth": {
    "type": "oauth2",
    "scopes": [],
    "access_summary": "Read and write the repositories you choose when installing the app."
  }
}

{
  "auth": {
    "type": "oauth2",
    "scopes": ["chat:write", "users:read"],
    "scope_descriptions": {
      "chat:write": "send messages as the CoreSpeed app",
      "users:read": "see workspace members"
    },
    "optional_scopes": ["canvases:write"],
    "optional_scope_descriptions": {
      "canvases:write": "create and edit canvases"
    },
    "user_scopes": ["chat:write", "im:write"],
    "user_scope_descriptions": {
      "chat:write": "send messages as you",
      "im:write": "start direct messages as you"
    }
  }
}