MCP server
Connect AI agents and MCP clients to a Snoze workspace.
Snoze ships a Model Context Protocol server, so any MCP client — Claude, coding agents, your own tools — can read and act on a workspace. It speaks Streamable HTTP at https://api.snoze.dev/mcp.
Connecting
Pick your client — the one-click buttons and official commands below need no configuration. The first time the client talks to Snoze, your browser opens to sign in and approve access:
https://api.snoze.dev/mcpSign in from your client when it first connects — no API key needed.claude mcp add --transport http snoze https://api.snoze.dev/mcpThen run /mcp inside Claude Code and pick snoze to sign in.
Two ways to authenticate
OAuth sign-in (default). The server implements the MCP authorization spec: an unauthenticated request returns 401 with a WWW-Authenticate hint pointing at /.well-known/oauth-protected-resource/mcp, and clients discover the authorization server and run the browser sign-in flow from there. The agent acts as the signed-in user — it can read and change exactly what that user's workspace role allows.
Workspace API key. Headless environments (CI, scripts, servers) can't open a browser. Send a workspace API key as a bearer token instead — no sign-in flow, and the agent is capped to the key's scopes rather than a user's full role. Create one at Settings → API keys.
{
"mcpServers": {
"snoze": {
"type": "http",
"url": "https://api.snoze.dev/mcp",
"headers": { "Authorization": "Bearer snoze_sk_YOUR_KEY" }
}
}
}Choosing a workspace
API keys are workspace-scoped, so they need nothing extra. With OAuth, the bare URL connects to the workspace the user picked when approving access (or their oldest one), and the server's instructions tell the agent which workspace it landed in (plus the alternatives). To pin a specific workspace, add its slug to the server URL:
https://api.snoze.dev/mcp?workspace=your-workspace-slugRead-only access
https://api.snoze.dev/mcp/readonly offers only the read tools, whatever the credential could otherwise do. Use it for agents that should search and summarize; it takes the same ?workspace= pin. It limits what the connection offers, not the credential: when nothing may ever change, use an API key with only read scopes.
Official install commands
The install card above fills these in; they're reproduced here for reference.
# For you, this project (default scope)
claude mcp add --transport http snoze https://api.snoze.dev/mcp
# For you, every project: --scope user
# For everyone on the project --scope project (commits a shared .mcp.json)Then run /mcp inside Claude Code to sign in. For Claude on web or desktop, add https://api.snoze.dev/mcp as a custom connector under Settings → Connectors.
codex mcp add snoze --url https://api.snoze.dev/mcp
codex mcp login snozecode --add-mcp '{"name":"snoze","type":"http","url":"https://api.snoze.dev/mcp"}'Cursor installs through the one-click button above, or manually under Cursor Settings → MCP with the generic JSON config.
What agents can do
The server's tools are Snoze's own assistant operations — the same ones the in-app assistant uses — so an external agent can do what Snoze's assistant can: build databases with typed fields and views, write records, compose pages in Markdown, build dashboards, forms, automations and whiteboards, comment, and work with calendars and connected apps. Inputs are intent-level: fields, options, people and dates are named in plain words, and Snoze compiles keys and checks everything. Authorization is identical to the product's: an OAuth agent is bounded by the signed-in user's role, an API-key agent by the key's scopes.
Tools
The exact list follows the caller's permissions. The main groups:
| Group | Tools |
|---|---|
| Find and read | search, fetch, open, map, query |
| Pages and content | pages_create, pages_edit, comments_list, comments_create, comments_resolve, files_save, files_link |
| Databases and records | databases_create, databases_update, databases_duplicate, records_create, records_update, sub_records_list, sub_records_configure, sub_records_move |
| Workspace items | items_update, items_move, items_duplicate, folders_create, delete |
| Dashboards and forms | dashboards_create, dashboards_update, forms_create, forms_update |
| Automations and actions | automations_catalog, automations_create, automations_update, automations_control, automations_runs, actions_create, actions_run |
| Whiteboards | canvas_create, canvas_read, canvas_compose, canvas_edit, canvas_arrange, canvas_undo |
| Calendar | calendar_range, calendar_create, calendar_update |
| Connected apps | connections_list, connections_get, integrations_search, integrations_view, integrations_operations, integrations_act, and connection management |
How results come back:
- Reads return data.
searchresults carry anid(pass it tofetchoropen) and aurlthat opens the item in Snoze. - Writes return a receipt:
status(verifiedorpartial), theaffectedresources with names and links, anything that could not be confirmed, and warnings. - Refusals are tool errors that name what was wrong and list the legal values — fields, options, candidates — so the agent can fix the call.
searchandfetchfollow the shapes ChatGPT's deep research and company knowledge expect.
Tools carry the standard MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), and Claude Code hints that keep discovery tools loaded and force a confirmation for deletions, irreversible changes and anything that writes outside Snoze. Acting in a connected app — which can include sending through a workspace Google connection — is marked for confirmation.
Resources and prompts
The most recently updated workspace items are MCP resources under the same references the tools use — surface://… for pages, notes, dashboards, forms and whiteboards, database://…, record://database/record, file://… — and read as Markdown (or JSON for structured items), so a client can attach them by @-mention. Snoze's guides are resources too (docs://references/databases.md and friends); agents read them before building something unfamiliar.
The server's prompts are the recipes Snoze's assistant follows: CRM pipeline, project tracker, content calendar, intake form with routing, meeting notes to actions, weekly report, spreadsheet import, dashboard and automation build-and-check. Claude Code lists them as /mcp__snoze__<name> commands.
Protocol
The server implements MCP revision 2026-07-28 (stateless, server/discover) and keeps serving clients on the 2025 revisions with the same tools. It is stateless — every request is independent — and answers JSON. Requests are capped at 1 MB and a single tool result at about 80,000 characters; larger results explain how to narrow the call. Long documents and large structured items come back in windows of about 50,000 characters, with the cursor to continue from. MCP calls carry no identity that survives a retry, so a client that resends a write after losing its response makes the change twice.
Safety
Signed in, the agent can never do more than the user's workspace role allows; with an API key, never more than the key's scopes; on /mcp/readonly, the connection offers nothing but reads. The workspace always comes from the credential, never from anything the model says. Every call goes through the same validation, permissions, plan limits and audit trail as the app. Your MCP client is where you approve tool calls, so its confirmation is the approval. Destructive and outward-facing tools are marked for confirmation, but the client decides whether to ask: one set to auto-approve runs them without asking. Deletions move items to the trash. To rule writes out, use /mcp/readonly or a key with read scopes. An API key's writes need a plan that includes API writes; after a downgrade it keeps reading.