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).
kind"remote-mcp"optional: Present only on org-registered remote MCP connectors. Absent on OAuth connectors — that absence is the discriminator.
categorystringrequired: "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: OAuth grant metadata. See the four shapes below. 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.
remote.oauthobjectoptional: Present when the upstream uses OAuth.

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": "connector",
      "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",
      "category": "connector",
      "name": "Acme internal tools",
      "description": "Org-registered remote MCP server at mcp.acme.internal (upstream self-described, unverified).",
      "url": "https://api.corespeed.io/connectors/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",
        "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"
    }
  }
}