# Overview (/docs/reference)

This reference documents the wire contract, one operation per page. If you are
setting up a client for the first time, start with the
[Getting started](/docs) — it covers browser sign-in and one-click install
instead of raw requests.

* **Base URL** — `https://api.corespeed.io`
* **Transport** — HTTPS, Streamable HTTP, stateless
* **Content type** — `application/json` on requests
* **Credentials** — an MCP OAuth token on `POST /mcp`, or an `sk-cs-…` API key,
  `sk-csa-…` agent key, or user session JWT anywhere

## MCP endpoint \[#mcp-endpoint]

Every connector and built-in tool is served from one endpoint, `POST /mcp`. The
transport is stateless: one JSON-RPC call per HTTP request. Arrays (JSON-RPC
batches) are rejected with `400`, a body over 5 MiB with `413`, and `GET /mcp`
answers `405` — there is no standalone server-to-client stream.

The endpoint serves both protocol eras. A 2025-era request is answered as one
`text/event-stream` event whose `data:` line is the JSON-RPC response. A
`2026-07-28` request, which carries a per-request `_meta` envelope, is answered
as plain `application/json`.

* [`POST initialize`](/docs/reference/mcp/initialize) — Negotiate the protocol version and read server capabilities.
* [`POST tools/list`](/docs/reference/mcp/tools-list) — Enumerate every tool visible to this caller right now.
* [`POST tools/call`](/docs/reference/mcp/tools-call) — Invoke one namespaced tool and read its result or isError payload.

## Connectors \[#connectors]

One authenticated call returns every connector visible to this caller, with
static metadata and the caller's own connection state in the same entry. There is
no per-connector fan-out and no unauthenticated catalog.

* [`GET /connectors`](/docs/reference/connectors/list) — Every visible connector with status and accounts\[].
* [`GET /connectors/:id`](/docs/reference/connectors/get) — One connector; 404 when the id is unknown or not offered here.
* [`DELETE /connectors/:id`](/docs/reference/connectors/delete) — Disconnects one of your own accounts. A remote MCP registration is deleted org-wide at /connectors/org/:slug.

## Tools \[#tools]

Built-in tool families are documented on their capability pages —
[Memory](/docs/memory), [Media](/docs/media), [Web](/docs/web),
[Social](/docs/social) — with `tools/list` as the authority for names and
schemas. The account-management family has its own reference:

* [`manage__*`](/docs/reference/tools/manage) — Keys, agents, connected accounts and their shares, environments, connect links, session, remote MCP servers, approval waits, and feedback — arguments and who may call each.

## Authentication \[#authentication]

Every endpoint in this reference requires a caller credential — an MCP OAuth
token on `POST /mcp` only, or an
`sk-cs-…` API key, `sk-csa-…` agent key, or
user session JWT anywhere — except the `GET /health` and `GET /version` probes,
the public server card at `GET /.well-known/mcp/server-card.json`, and the
metadata document below. The header forms, and how each credential is issued, are on
[Authentication](/docs/authentication).

### Browser sign-in \[#browser-sign-in]

An unauthenticated `POST /mcp` returns `401` with a `WWW-Authenticate` header
naming the RFC 9728 protected-resource metadata document:

```json title="GET /.well-known/oauth-protected-resource/mcp"
{
  "resource": "https://api.corespeed.io/mcp",
  "authorization_servers": ["https://login.corespeed.io"],
  "bearer_methods_supported": ["header"]
}
```

The client then reads the authorization server's RFC 8414 metadata, registers
itself, runs OAuth 2.1 + PKCE in the browser, and retries with the issued token.
CoreSpeed is only the resource server — it issues and stores no OAuth tokens.

## Conventions \[#conventions]

* **Tool names** are `<capability-id>__<operation>` with a double underscore:
  `memory__remember`, `slack__post_message`. A remote MCP server your
  organization added publishes `org__<slug>__<tool>`.
* **Your surface is not a static list.** The public server card lists only the
  built-in tools. Discovery is per caller: read `GET /connectors` for connector
  and account state, and MCP `tools/list` for the callable surface.
* **Two error layers.** HTTP failures carry one nested `error` envelope with
  `type`, `code`, and `message` (the MCP transport's own refusals are bare
  JSON-RPC errors); tool failures arrive inside HTTP `200` with
  `result.isError: true`. Both layers and every envelope shape are listed in
  [Errors & status codes](/docs/reference/errors).
* **URLs in responses** (`mcp_url`, `icon_url`, `url`) are derived from the
  request origin, so they match the host you called.

`api.corespeed.io` is the production host and is live, with browser sign-in
advertised by the production OAuth issuer. Samples on these pages are written
against it. `api.staging.corespeed.io` runs the same worker from `main` and is
the test range — keys are per-environment, so a production key is rejected
there.