Authentication

Waydock's MCP server authenticates with per-user bearer API keys, not OAuth. Each user issues and revokes their own keys, each key carries an explicit scope set, and every call is audited. New here? Start with the Quickstart.

For agents: send Authorization: Bearer wdmcp_... on every request to https://waydock.ai/api/mcp/stream. Waydock does not run an OAuth authorization server for MCP, so there is no /.well-known/oauth-authorization-server and no dynamic client registration. The machine-readable version of this page is /auth.md.

The key

A Waydock MCP key looks like this:

wdmcp_a1b2c3d4_9f8e7d6c5b4a39281706f5e4d3c2b1a0

The wdmcp_ prefix, a short public segment, and a long random secret. The key is shown once at creation. Waydock stores only a SHA-256 hash of it, never the key itself, and verifies with a constant-time comparison.

Issuing a key

1. Sign in and open Settings → Account → MCP (/settings/account/mcp).
2. Click Create key and choose a scope preset (Read & email myself or Full access) or a custom scope set. See Scopes & presets.
3. Name the key after the agent that will use it (for example claude-desktop, cursor, nightly-brief-bot). The name appears in your audit log next to every call.
4. Copy the key. It is not shown again.

You can hold up to 3 live keys on Free and 5 on Pro. New keys are read-only by default.

Sending the key

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

Authorization: Bearer wdmcp_xxxxxxxx

The X-API-Key: wdmcp_xxxxxxxx header is also accepted. Keys created before a past rename may start with the legacy ddmcp_ prefix; those still authenticate.

Optional restrictions per key

Each key can be locked down further, all enforced at authentication time:

• Expiry. Set an expiry date; the key stops authenticating the moment it passes.
• IP allowlist. Restrict a key to one or more CIDR ranges. A call from an address outside the list is rejected before any tool runs.
• Tool denylist. Block specific tools for a key regardless of its scopes. Useful to hand an agent broad read scopes but withhold, say, waydock_send_email.

Lifecycle

• Rotate. Generate a fresh secret for an existing key without changing its id or scopes. The old secret stops working immediately, and the new one is shown once. Use this if a key may have leaked.
• Revoke. Delete a key instantly. Because the app UI and the MCP endpoint read the same key record, revoking stops both in the same moment.
• History. Every key keeps a change log (create, update, rotate, revoke, re-consent), and every call is written to the audit log with the agent name, tool, outcome, and latency.

Re-consent when scopes are added

Each key is stamped with the scope catalog version it was created under. When Waydock adds new optional scopes to the catalog, an existing key does not silently gain them. The key is flagged as pending re-consent, and the owner explicitly acknowledges the new version to pick up any new scopes they want. Existing grants are never changed without the owner's action.

Rate limits and idempotency

• Daily call ceiling follows the plan: 500 per day on Free, 100,000 on Pro, plus a per-IP window. Call waydock_quota (no scope required) for your remaining budget.
• Idempotency. Send an Idempotency-Key header (or X-Idempotency-Key) on a write request and Waydock returns the cached response for a repeat of the same key, so a retried send does not fire twice.

Discovery endpoints

Security properties

• Keys are stored as a SHA-256 hash, never in plaintext, and compared in constant time.
• Outbound send is wildcard-proof: a key cannot send to third parties unless its scope list contains the literal write:mail.send. No preset or wildcard satisfies it.
• Every call is scope-checked and, for paid write scopes, entitlement-checked at call time.
• All access is logged to one audit trail shared by the app and the agent endpoint.

See also

• Quickstart for client configs
• Tool reference for tools, scopes, and presets
• Security for the outbound-safety contract