# Authenticating with Waydock

Waydock exposes a Model Context Protocol (MCP) server so AI agents can read and
act on a user's unified context (mail, meetings, calendar, tasks).

## Authentication model

Waydock uses **per-user bearer API keys**. Each user issues and revokes their own
keys; a key carries an explicit scope set and is audited per call. Waydock does
**not** currently operate an OAuth authorization server for MCP, so there is no
`/.well-known/oauth-authorization-server` and no dynamic client registration
endpoint.

## Endpoints

- MCP endpoint: https://waydock.dokploy.underdogs.dev/api/mcp/stream (transport: streamable-http)
- Server card: https://waydock.dokploy.underdogs.dev/.well-known/mcp/server-card.json
- Manifest (tools + scopes): https://waydock.dokploy.underdogs.dev/api/mcp/manifest
- Health: https://waydock.dokploy.underdogs.dev/api/mcp/health

## Per-user API key

Each user issues and revokes their own keys. A key carries an explicit scope set
and every call is audited.

1. Sign in to Waydock and open **Settings → Account → MCP** (https://waydock.dokploy.underdogs.dev/settings/account/mcp).
2. Create a key, choosing a scope preset ("Read & message yourself" or "Full
   access") or a custom scope set. Sending email to other people is always a
   separate, explicit opt-in and is never granted by a preset.
3. Copy the key (prefix `wdmcp_`). It is shown once. Keys are revocable at any
   time, and every call is recorded in a per-key audit log.

Send the key as a bearer token on every MCP request:

```
Authorization: Bearer wdmcp_xxxxxxxx
```

The `x-api-key: wdmcp_xxxxxxxx` header is also accepted.

### Example client config (Claude Desktop)

```json
{
  "mcpServers": {
    "waydock": {
      "type": "http",
      "url": "https://waydock.dokploy.underdogs.dev/api/mcp/stream",
      "headers": { "Authorization": "Bearer YOUR_MCP_KEY" }
    }
  }
}
```

## Scopes

Scopes are namespaced `read:*` / `write:*`. Outbound send to other people
requires the literal `write:mail.send` scope and is wildcard-proof: no preset or
wildcard grant can satisfy it. `write:mail.send.self` is the narrower grant that
can only reach the user's own verified inboxes. See the manifest for the full
scope catalog and the tools each scope unlocks.