# Auth.md — callsend authentication for agents and humans

callsend is voice supervision for background coding agents: agents call
their human when work lands. Three principals authenticate, three ways.

## Humans (web app)

Sign in with GitHub via Clerk at https://callsend.dev. OIDC discovery:
https://callsend.dev/.well-known/openid-configuration (issuer
`https://clerk.callsend.dev`).

## Machines (the connector)

The connector runs on the machine where your coding agents live.

```sh
curl -fsSL https://callsend.dev/install | sh
callsend login      # opens a one-time approve link in the web app
```

`callsend login` performs a device pairing: the CLI gets a bearer token,
scoped to your account (single `api` scope, full account access), stored
locally. Revoke it any time from Settings.
All connector calls to `https://api.callsend.dev` send it as
`Authorization: Bearer <token>` (see
https://callsend.dev/.well-known/oauth-protected-resource).

## Agents (remote MCP, recommended)

The remote MCP endpoint runs no code on the user's machine — it is a plain
HTTP call to callsend, which is what permission classifiers care about.

```
POST https://api.callsend.dev/mcp   (streamable HTTP)
```

Auth is OAuth 2.0 or a pre-shared bearer token:

- **OAuth (interactive)**: the client discovers the authorization server at
  https://api.callsend.dev/.well-known/oauth-authorization-server and the
  protected resource at
  https://api.callsend.dev/.well-known/oauth-protected-resource, then runs the
  standard code flow. The consent step sends the browser to
  https://callsend.dev/oauth/approve, where the signed-in human approves the
  agent by name. Approving binds the grant to that human — an agent can only
  ever call its own human.
- **Bearer token (headless/CI)**: mint a connector token in Settings and send
  it as `Authorization: Bearer <token>` on the MCP request. Clients without
  OAuth (e.g. `claude mcp add … --header "Authorization: Bearer <token>"`) use
  this.

Add it per client:

```sh
claude mcp add --transport http callsend https://api.callsend.dev/mcp   # then /mcp to sign in
codex mcp add callsend --url https://api.callsend.dev/mcp
```

```json
{ "mcpServers": { "callsend": { "url": "https://api.callsend.dev/mcp" } } }
```

## Agents (local stdio MCP)

For the full connector (dispatch to the local machine), after `callsend login`
any MCP client on that machine can ring you over stdio:

```json
{ "mcpServers": { "callsend": { "command": "callsend-mcp" } } }
```

`callsend-mcp` reuses the connector pairing — no extra secrets. The agent
gets a `call_me` tool (reason + context). Pairing scopes calls: an agent can
only ever call its own human. Server card:
https://callsend.dev/.well-known/mcp/server-card.json

## Notes for crawling agents

Marketing pages negotiate to markdown (`Accept: text/markdown`). Product
reference: https://callsend.dev/llms.txt (full: /llms-full.txt). GitHub
access used for call briefs is read-only and revocable.