# Quickstart

_Last updated: July 7, 2026_

Give an AI agent secure, governed access to your work context — email, calendar, meetings, and tasks — in about five minutes.

Waydock is a secure agent-context layer. You connect your mailboxes and tools once, mint a scoped key, and any MCP-compatible agent (Claude, Cursor, your own code) can read and act on your behalf inside guardrails you control. Every call is scope-checked, allowlist-gated, and written to an audit log.

> **For agents:** the MCP endpoint is `https://waydock.ai/api/mcp/stream` (Streamable HTTP, protocol `2025-06-18`). Authenticate with `Authorization: Bearer wdmcp_...`. Call `waydock_capabilities` (no scope required) for the live tool list. This page is available as Markdown at [/docs/quickstart.md](/docs/quickstart.md) and the whole doc set at [/llms.txt](/llms.txt).

## What you'll build

By the end, an agent will answer *"What's on my plate this morning?"* from your live inboxes and calendar, with a provenance trail showing where each fact came from.

- **Time to first result:** about 5 minutes
- **Prerequisites:** a Waydock account and one connected mailbox (Google or Outlook)

## Step 1 — Create your account and connect a mailbox

1. Sign up at [waydock.ai](https://waydock.ai) with Google or Microsoft.
2. On first run the setup wizard walks you through connecting a mailbox. Or go to **Settings → Connections** and connect **Google** or **Outlook** via OAuth.

Waydock stores metadata and snippets, reads your mail live at query time, and never trains on your data. You can connect multiple accounts and providers (Google, Outlook, Linear, Jira, Teams, Fathom, Fireflies, Pocket).

✅ **Check:** your inbox populates under **Today**.

## Step 2 — Mint a scoped MCP key

1. Go to **Settings → Account → MCP** ([/settings/account/mcp](/settings/account/mcp)).
2. Click **Create key**.
3. Choose a permission preset:

| Preset | What it can do | Plan |
| --- | --- | --- |
| **Read & email myself** _(default)_ | Read your briefings, mail, meetings, tasks, and calendar. Email summaries or replies **to your own inboxes only**. | Free |
| **Full access** | Every read and write scope **except** sending mail or Teams messages to third parties (those stay a separate, explicit opt-in). | Pro |

4. Name the key after the agent that will use it (e.g. `claude-desktop`, `cursor`, `nightly-brief-bot`) — the name shows up in your audit log.
5. Copy the key. **It is shown once.**

Keys look like this:

```text
wdmcp_a1b2c3d4_9f8e7d6c5b4a39281706f5e4d3c2b1a0
```

You can hold up to **3 live keys on Free, 5 on Pro**. Revoke any key with one click.

> **Least privilege by default.** The free preset can never email anyone but you. Sending to third parties (`write:mail.send`) and Teams (`write:teams.send`) are always separate, deliberate grants — never bundled into "Full access."

✅ **Check:** the new key appears in your key list with its preset and creation time.

## Step 3 — Point your agent at Waydock

Waydock speaks the Model Context Protocol over Streamable HTTP.

- **Endpoint:** `https://waydock.ai/api/mcp/stream`
- **Auth:** `Authorization: Bearer wdmcp_...` _(or `X-API-Key: wdmcp_...`)_
- **Protocol:** MCP `2025-06-18`

Pick your client. Every snippet is copy-paste-correct — replace only the key.

### Claude Desktop

Edit `claude_desktop_config.json` (**Settings → Developer → Edit Config**). The auth header contains a space, so pass it through an env var — otherwise it gets split into two arguments:

```json
{
  "mcpServers": {
    "waydock": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://waydock.ai/api/mcp/stream",
        "--header",
        "Authorization:${WAYDOCK_AUTH}"
      ],
      "env": {
        "WAYDOCK_AUTH": "Bearer wdmcp_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop; the Waydock tools appear under the 🔌 icon.

### Claude Code (CLI)

```bash
claude mcp add --transport http waydock https://waydock.ai/api/mcp/stream \
  --header "Authorization: Bearer wdmcp_your_key_here"
```

### Cursor

Add to `~/.cursor/mcp.json` (or **Settings → MCP → Add**):

```json
{
  "mcpServers": {
    "waydock": {
      "url": "https://waydock.ai/api/mcp/stream",
      "headers": {
        "Authorization": "Bearer wdmcp_your_key_here"
      }
    }
  }
}
```

### VS Code (Copilot / MCP)

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "waydock": {
      "type": "http",
      "url": "https://waydock.ai/api/mcp/stream",
      "headers": {
        "Authorization": "Bearer wdmcp_your_key_here"
      }
    }
  }
}
```

### Raw HTTP (curl)

Streamable HTTP requires an `Accept` header that allows both JSON and the event stream:

```bash
# Put your key in an env var first (grab it from Settings → Account → MCP):
export WDMCP_KEY=wdmcp_your_key_here

curl -sN https://waydock.ai/api/mcp/stream \
  -H "Authorization: Bearer $WDMCP_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "waydock_whoami", "arguments": {} }
  }'
```

### Python (SDK)

```python
import asyncio
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

URL = "https://waydock.ai/api/mcp/stream"
HEADERS = {"Authorization": "Bearer wdmcp_your_key_here"}

async def main():
    async with streamablehttp_client(URL, headers=HEADERS) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("waydock_briefing", {})
            print(result.content)

asyncio.run(main())
```

### TypeScript (SDK)

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://waydock.ai/api/mcp/stream"),
  { requestInit: { headers: { Authorization: "Bearer wdmcp_your_key_here" } } }
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const briefing = await client.callTool({ name: "waydock_briefing", arguments: {} });
console.log(briefing.content);
```

✅ **Check:** call `waydock_whoami` (no scope required). You should get back your account email and org. A `401` means the `Bearer ` prefix is missing or the key was truncated on paste.

## Step 4 — Ask your first question

In your agent, ask in plain language:

> **What's on my plate this morning? Summarize anything that needs a reply.**

Behind the scenes it calls tools like `waydock_briefing`, `waydock_inbox`, and `waydock_follow_ups_list` and answers from live data. Every result carries a provenance chip (which mailbox, which message).

Prefer to drive it yourself? Two direct calls:

```bash
# Assumes WDMCP_KEY is set (see Step 3).
# Your daily briefing
curl -sN https://waydock.ai/api/mcp/stream \
  -H "Authorization: Bearer $WDMCP_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"waydock_briefing","arguments":{}}}'

# Live-search your mailboxes
curl -sN https://waydock.ai/api/mcp/stream \
  -H "Authorization: Bearer $WDMCP_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"waydock_mail_search","arguments":{"query":"invoice from acme"}}}'
```

✅ **Check:** the briefing call returns a summary object. You're connected.

## Step 5 — Do something (safely)

Reading is read-only. When you're ready to act, the **free** preset lets an agent email *you* — perfect for "send me a summary of today" with no risk of it messaging a customer.

```bash
# Assumes WDMCP_KEY is set (see Step 3).
curl -sN https://waydock.ai/api/mcp/stream \
  -H "Authorization: Bearer $WDMCP_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc":"2.0","id":3,"method":"tools/call",
    "params":{
      "name":"waydock_send_email",
      "arguments":{
        "to":["you@example.com"],
        "subject":"My morning brief",
        "body":"Plain-text summary of what needs attention today."
      }
    }
  }'
```

To send to *other* people, upgrade to Pro and grant `write:mail.send` explicitly. Recipients must be on your [outbound allowlist](/settings/account/email-allowlist), and server-enforced caps apply: **500 sends per 24h** and **20 per 24h to any single address** by default (clamped to hard ceilings), a **60-second cooldown** on newly added recipients, and a global kill switch.

🎉 **That's the quickstart.** You have an agent reading your work context and acting inside guardrails you set.

## Concepts (the 2-minute mental model)

- **Waydock is the context layer, not the model.** You bring the agent; Waydock is the secure, governed doorway to your data.
- **Mira** is Waydock's built-in assistant — the same tools, in-app, if you don't want to bring your own agent.
- **Scopes** are what a key *can* do. **Presets** are curated bundles of scopes. Least privilege is the default.
- **Allowlist + caps** govern outbound actions, enforced server-side no matter what the agent is told.
- **Provenance** travels with every read, so answers are auditable, not hallucinated.
- **Everything is logged.** Every tool call — key, tool, outcome, duration — lands in your audit log.

## Tool reference

Waydock exposes 50+ tools (call `waydock_capabilities` for the live, authoritative list for *your* key and plan). The ones you'll reach for most:

### Read

| Tool | Does | Scope |
| --- | --- | --- |
| `waydock_briefing` | Your current briefing summary | `read:briefing` |
| `waydock_inbox` | Pending inbox cards | `read:cards` |
| `waydock_calendar` | Pending calendar cards | `read:cards` |
| `waydock_mail_search` | Live-search connected mailboxes | `read:mail.search` |
| `waydock_mail_list` | List archived mail (filters, paging) | `read:mail` |
| `waydock_mail_get` | Fetch one email by id | `read:mail` |
| `waydock_mail_count` | Count mail matching filters | `read:mail` |
| `waydock_follow_ups_list` | Action items others owe you | `read:meetings` |
| `waydock_meetings_list` | Recent meetings (Fathom + Fireflies) | `read:meetings` |
| `waydock_tasks_list` | Jira + Linear tasks | `read:tasks` |
| `waydock_accounts` | Connected providers | `read:accounts` |

### Act

| Tool | Does | Scope |
| --- | --- | --- |
| `waydock_send_email` | Send plain-text email (allowlist-gated) | `write:mail.send.self` / `write:mail.send` |
| `waydock_card_action` | Archive / snooze / act on a card | `write:cards` |
| `waydock_card_feedback` | Signal important / not important | `write:cards` |
| `waydock_task_create` | Create a Jira or Linear issue | `write:tasks` |
| `waydock_sync` | Trigger a mail/calendar sync | `write:sync` |

### Always available (no scope)

`waydock_whoami` · `waydock_capabilities` · `waydock_health` · `waydock_version` · `waydock_quota`

## Scopes & permissions

Scopes follow `<kind>:<resource>[.<sub-resource>]`. Kinds: `read`, `write`, and `destructive` (mail/Teams send).

**Presets:**

- **`read-and-self-send`** — every read scope plus `write:mail.send.self`. Free. The default.
- **`full-access`** — every scope **except** `write:mail.send` and `write:teams.send`. Pro.

**Sending is never bundled.** `write:mail.send` (third-party email) and `write:teams.send` are always granted on their own, on purpose. A "Full access" key still cannot email a customer until you add that scope deliberately.

## Security you can hand to your CISO

- **Scoped, revocable keys** — mint one per agent, revoke instantly. Free caps at 3 live keys, Pro at 5.
- **Outbound allowlist + capped sends** — 500 sends/24h and 20/recipient/24h by default and a 60-second new-recipient cooldown, all enforced server-side regardless of prompt. Caps are clamped to hard server ceilings (2000/day, 100/recipient); the cooldown and kill switch are fixed in code.
- **Kill switch** — one toggle stops all outbound mail from every path.
- **Full audit log** — every MCP call recorded with tool, outcome, status, duration, and the calling agent's name.
- **Least-privilege presets** — read-only and self-send-only defaults; destructive sends are opt-in.
- **Tenant isolation** — keys are org-scoped with row-level security enforced in the database.
- **No training on your data.** Reads are live and provenance-tracked.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `401 Unauthorized` | Missing/typo'd key | Ensure `Authorization: Bearer wdmcp_...`; re-copy the full key |
| `403 Forbidden` on a tool | Key lacks the scope | Check the tool's scope above; re-mint with the right preset |
| `406 Not Acceptable` (curl) | Missing `Accept` header | Add `Accept: application/json, text/event-stream` |
| Header split into two args (Claude Desktop) | Space in `--header` value | Use the `env`-var pattern shown above |
| `429 Too Many Requests` | Rate limit | Honor the `Retry-After` header and back off |
| `upgrade_required` on a write | Write needs Waydock Pro | Upgrade, then grant the write scope |
| Email won't send | Recipient not allowlisted, or self-send-only key | Allowlist the recipient (Pro), or send to your own inbox |

Duplicate-safe writes: pass an `Idempotency-Key` header and retries won't double-send.

## Next steps

- **[Manage MCP keys](/settings/account/mcp)** — create, scope, name, and revoke keys
- **[Security](/security)** — the full outbound-safety contract
- **[Pricing](/pricing)** — Free vs Pro
- **[Contact](/contact)** — talk to us

_Prefer to talk to a machine? Every docs page has a Markdown twin — append `.md` to the URL — and the whole set is summarized at [/llms.txt](/llms.txt) and concatenated at [/llms-full.txt](/llms-full.txt)._