// 00 — MCP references

MCP references

wspc exposes its agent surface — todo, calendar, email, projects, org — through a single remote MCP server at https://mcp.wspc.ai/mcp. Any host that speaks MCP (Claude Desktop, Hermes, Cursor, a custom orchestrator) can register the URL, complete the OAuth handshake once, and then read and write the same workspace a human would through the web console.

This page is a quick reference: which tools exist, what each does in one line, and what a typical agent call looks like. The live tools/list response is the authoritative schema — fetch it any time the prose here disagrees.

// 01 — Connection

Connection

Point your MCP host at the server below. Step-by-step setup instructions for each client are in QUICKSTART.

The server advertises tools capabilities only. List tools with the standard tools/list request once the host has a valid bearer token.

// 02 — Authentication

Authentication

Every MCP request carries Authorization: Bearer <token>. Tokens come from the OAuth 2.1 remote flow — dynamic client registration, browser-driven authorization, and an email magic code for proof of identity. The MCP host runs the dance on first connect and again whenever the access token expires.

When a request arrives without a token, or with one the server cannot verify, the response is 401 Unauthorized with a WWW-Authenticate header pointing at https://mcp.wspc.ai/.well-known/oauth-protected-resource. MCP hosts that support OAuth discovery use that URL to relaunch the flow automatically.

The single issued scope is wspc:full — root-level access for the authenticated user. Finer-grained scopes are not available yet.

// 03 — Tools

Tools

Seventy-seven tools across seven domains. Each one accepts a JSON object input and returns either a structured result or an isError payload with a stable error code. The summaries below are intentionally short — fetch tools/list for full input schemas, required fields, and the exact error codes each tool can return.

Todo

Tasks with hierarchy, status, due dates, optimistic locking, and project-scoped types with custom fields.

Calendar

calendar_list_events 的 q 以 literal substring 搜尋 title、description、location，支援長字串與 UTF-8。ASCII 比對不分大小寫；%、_ 是一般字元，不是 wildcard。

Imported Event 與 Agenda single item 的 invitation 保留外部 UID／Organizer。calendar_update_event 對 Imported Event 回 IMPORTED_EVENT_READ_ONLY；delete／restore 只切換 Calendar Trash，不寄 attendee 通知。email_get 保留 optional calendar_sync，只有具備 Calendar read 權限才包含 event_id。同步結果描述該封通知當時的處理，不代表 Event 目前狀態。此版收件同步預設停用，待 provider 驗證後才啟用。

Calendar 支援 attendees、ISO 8601 時間、跨 DST 的 IANA time-zone Series、iCalendar 匯出與 optimistic locking.

Todo, project, calendar, and email tool calls participate in the same per-database consistency bookmark contract as their HTTP APIs. MCP clients should store and resend each returned bookmark header independently: x-cb-todo for todo/project tools, x-cb-cal for calendar tools, and x-cb-email for email tools. The bookmark values are opaque transport headers; they are not included in MCP tool output bodies.

私人 Calendar 訂閱

使用 calendar_get_subscription 讀取目前狀態，calendar_create_subscription 建立或重新取得相同的有效 URL。兩者不需要輸入；結果為 { enabled, version, url }，停用時 url 是 null。calendar_reset_subscription 與 calendar_disable_subscription 需要 { expected_version }，且標為 destructive。版本過時回 VERSION_CONFLICT；不確定上次操作結果時，先 get 最新狀態再重試。管理操作只使用目前帳號及 Workspace，不接受 caller 指定 owner。

URL 可讀取該使用者在目前 Workspace 的所有過去與未來 Events，含取消狀態及 recurrence，排除 Trash；取得 URL 的人都能讀取完整活動內容，請勿公開分享。Reset 立即使舊 URL 失效並要求外部 calendar 重新訂閱；disable 停止存取，但無法刪除外部已保存的副本。訂閱 token 不能作為一般 REST／MCP Bearer credential。功能未啟用時回 SUBSCRIPTION_UNAVAILABLE。

Google Calendar 電腦版使用 Other calendars → From URL 貼上私人 URL。外部更新時間由 calendar app 決定，可能延遲；下載再 import 檔案只會產生一次性副本。

Email

Inbound mail under user-controlled aliases, outbound send with attachments, batch read / unread / delete.

email_get 與 email_send 都會回傳 { email, attachments, attachment_availability }；email_send 另含 idempotent_replay。每個 attachment item 只含 idx、filename、mime_type 與 size_bytes，不會暴露 storage key 或 digest。當保存的 metadata 數量與 email.attachment_count 不一致時，attachment_availability 是 unavailable 且 attachments 是空陣列；仍可用 email_attachment_get 嘗試讀取特定 received 或 sent attachment 的內容。

Email aliases

Platform Email Domain @wspc.app 的地址依 Current Workspace tier 計算容量：Free 3、Personal 10、Startup 40、Business 200。同一上限也適用於 Workspace 的 rolling 30-day creation budget；刪除釋放 active capacity，但不會重設建立額度，restore 也不算新建立。額度耗盡時回 ALIAS_CREATION_LIMIT_EXCEEDED；custom-domain aliases 不使用此額度，維持每位使用者最多 10 個 active aliases。Alias identifier 是完整 email address，可使用 @wspc.app 或同 organization 已完整 verified 且 enabled 的 Custom Email Domain。平台 local part 維持 5–32 字元；custom domain 接受 1–64 字元，例如 me@example.com。兩者皆以英數開頭，僅允許英數、點、底線與連字號，並轉成 lowercase；reserved words 只限制平台地址。Custom domain 未註冊於目前 organization 時回 ALIAS_DOMAIN_NOT_FOUND；verification 尚未完整或 domain 受限時回 ALIAS_DOMAIN_NOT_READY。Billing 失敗時回 EMAIL_ENTITLEMENTS_UNAVAILABLE，不建立地址。刪除後停止收取新信、釋放容量並保留歷史郵件。

Email domains

Startup and Business Workspaces can register one unverified custom-domain candidate at a time, manage DNS verification records, and delete unused domains. Free and Personal cannot register custom domains. New domains use Resend for sending and receiving; existing Pete bindings remain on pete-mail. Verification does not by itself guarantee mail use: the domain must also be enabled by the effective Workspace entitlement. Entitlement loss restricts excess domains without deleting domains, addresses, or messages. Inbound delivery is handled by an operator-managed provider webhook; there is no MCP tool for webhook registration. DNS records may include a purpose hint such as identity_verification, dkim, mail_from, receiving_mx, or dmarc so operators know why each record is required.

Drive

Organization-scoped file libraries: store, edit, move, version, and search text files and images.

Move／delete 的 confirmation 全部 required，版本須為大於等於 1 的 safe integer。缺失／無效欄位回 VALIDATION_ERROR；Library 不可見回 NOT_FOUND；來源 identity、path 或版本改變回 VERSION_CONFLICT；適用 purge claim 回 PURGE_IN_PROGRESS。以刪除前版本重送不是 unchanged。Adapter 原樣轉送確認，conflict 後須重新檢視並取得使用者確認，不得以 fresh lookup 替換 identity／版本自動重送。Response 遺失時先按 identity 讀回，無法判定就保留 unknown。

Drive 歷史還原

drive_file_restore 的 required fields 為 library_id、entry_id、path、expected_entry_version、version_id。Entry Version 必須是大於等於 1 的 safe integer；它不是 retained version 的 ID 或 version_number。使用 manifest 中經使用者確認的 entry identity／version，不得自動讀最新值補上缺欄位，舊格式會被拒絕。

VERSION_CONFLICT 表示確認後 entry 已改變、移動、刪除或被另一 entry 取代，需重新檢視並取得確認；同 hash 也不豁免。Source 必須屬於同一 entry／Library／Workspace；不存在回 FILE_NOT_FOUND，已有 purge claim 回 PURGE_IN_PROGRESS。成功結果只可能是 updated 或 unchanged，不會建立或復活 entry。先確認 live tools/list 的 required fields，再啟用依賴此保護的 flow。Timeout 後讀回 identity、Entry Version、current version 與 hash 判斷結果，不自動換新確認重送。

Drive 搜尋續頁

drive_search 首次傳 { "library_id": "<id>", "query": "launch plan", "limit": 20 }，續頁加入前頁 next_cursor 作為 cursor。保持 Workspace、library 與 query 逐字相同；沒有 next_cursor 就停止。limit 為 optional integer，預設 20、夾至 1–50，可在續頁調整；非整數或錯誤型別回 input validation error。

Search Cursor 無 TTL，與 D1 bookmark 不可互換；沿用 x-cb-drive bookkeeping。索引不變時按 relevance／內部 file ID 翻頁不重不漏；包括其他 library 在內的索引變動可能造成重複或遺漏，這不是 snapshot 或完整匯出。時間或 anchor 刪除不使 cursor 失效。VALIDATION_ERROR 應重新搜尋，NOT_FOUND 應停止並處理 library 存取權；每頁都重新檢查目前權限。網路錯誤保留舊結果與 cursor，成功才追加；不要無限 retry。HTTP 使用方式見 CLI 文件的 HTTP example。

Projects

Org-scoped containers for todos. Each project defines a default todo type for new work.

Org

Organization metadata. In v1 every user belongs to a single personal organization.

Member removal tool details

• Tool Name: auth_org_member_remove
• Description: Remove a member from the authenticated user’s organization, or leave the organization (self-removal).
• Input Parameters:
  • id (string, required): The ID of the user to be removed (e.g. usr_01KT4FF78A1F9CT5SWN5HK392F).
• Usage & Safety Warning:
  • Revert Behavior: Removing a member reverts their active organization back to their previous organization (previous_org_id).
  • Self-Removal (Leave): Any user (except the creator of the organization) can remove themselves, which is semantically equivalent to leaving the organization.
  • Creator Protection: The creator of the organization (created_by_user_id) cannot be removed.
  • Revert Constraint: A user cannot be removed if their previous_org_id is null, protecting against “homeless” states.

Guide

// 04 — Examples

Examples

Three sketches of what an agent does when a human asks it something natural. The shape — utterance, tool call, a note — repeats. The tool names and field names track real MCP inputs; the exact JSON the host sends is what tools/list describes.

Schedule a lunch

“Book lunch with Alice tomorrow at 12:30, one hour, at Taipei HQ. Her email is alice@example.com.”

calendar_create_event({
  title:      "Lunch with Alice",
  start:      "2026-05-27T12:30:00+08:00",
  end:        "2026-05-27T13:30:00+08:00",
  location:   "Taipei HQ",
  attendees:  [{ email: "alice@example.com", display_name: "Alice" }],
  idempotency_key: "lunch-alice-20260527-1230"
})

start and end are ISO 8601 datetimes with offset. The agent resolves the user’s “tomorrow” against the local timezone before constructing the call; the server itself only accepts ISO. An iCalendar invite is dispatched to the attendee on creation. For create retries, send a stable idempotency_key; the same key with the same payload returns the existing event, while a changed payload returns IDEMPOTENCY_KEY_REUSED.

For a recurring series, pass recurrence_rule as an RFC 5545 RRULE value without the RRULE: prefix. All-day series require date-only start/end and DATE UNTIL. Timed series may use UTC, or provide time_zone with matching offset-bearing local start/end; timed UNTIL remains UTC. The server returns a canonical rule and canonical IANA zone. On update, omit the fields to preserve them, pass an empty recurrence_rule to clear recurrence and its zone, or pass an empty time_zone to preserve the instants and return the series to UTC semantics. Update, cancel, delete, and restore affect the whole series; list calls return the persisted series master without expanding occurrences.

Triage the open backlog

“What todos do I still have open this week?”

todo_list({
  status:     ["open", "in_progress"],
  due_after:  "2026-05-26",
  due_before: "2026-06-02"
})

The agent maps “this week” to a half-open [due_after, due_before) window and filters by the two active statuses. Both bounds are date-only ISO strings; due_after is inclusive, due_before is exclusive.

Clear the unread queue

“Mark all my unread emails as read.”

email_list({ unread_only: true })
// → [{ id: "em_abc123", ... }, { id: "em_def456", ... }]

email_mark_read({ ids: ["em_abc123", "em_def456"] })

email_list returns unread items in cursor-paginated batches (default 20, max 100). email_mark_read takes a batch of ids in one call. If the inbox has more than limit unread emails, the agent re-calls email_list with the returned next_cursor until exhausted.

Recurring task with a checklist

“Every morning I do a standup: write notes, then post the summary. Set that up as a daily task.”

todo_rule_create({
  title:    "Daily standup",
  rrule:    "FREQ=DAILY",
  dtstart:  "2026-06-10",
  project_id: "prj_abc"
})
// → { rule: { id: "tdr_xyz" }, template_todo_id: "tod_tmpl", ... }

todo_create({ title: "Write notes",   parent_id: "tod_tmpl", project_id: "prj_abc" })
todo_create({ title: "Post summary",  parent_id: "tod_tmpl", project_id: "prj_abc" })

A rule owns a hidden template todo. To make the same subtasks appear on every occurrence, the agent attaches them to the template — not to one day’s instance. The template id comes back as template_todo_id from todo_rule_create (or as template.id from todo_rule_get). Adding a child under the template re-materializes future occurrences so each daily todo carries the checklist. Subtasks are one level deep; attaching to a specific day’s instance would only affect that day.

// 05 — Reference

Reference

• Live tools/list — POST https://mcp.wspc.ai/mcp with a tools/list JSON-RPC body. Returns the canonical name, description, and JSON Schema input for every registered tool. Treat the response as the source of truth whenever this page disagrees.
• HTTP equivalents — every MCP tool here maps to one or more REST endpoints documented in API REFERENCES.
• CLI equivalents — the same surface from a terminal lives in CLI REFERENCE.
• Setup walkthrough — setup steps for each client are in QUICKSTART.

// 06 — Troubleshooting

Troubleshooting

• 401 Unauthorized on every call — the request carries no bearer token, an expired one, or a token issued for a different resource. The response includes a WWW-Authenticate header pointing at https://mcp.wspc.ai/.well-known/oauth-protected-resource; OAuth-aware hosts use it to relaunch the flow. If your host does not auto-reconnect, remove and re-add the server to redo the handshake.
• Authorization never completes — the flow finishes in the browser with an email magic code. Make sure pop-ups are allowed for your host and that you can receive mail at the address you entered; enter the code to finish. Tokens expire, so an idle connection eventually re-prompts.
• 405 Method Not Allowed on GET /mcp — expected. The server is stateless and exposes no server-to-client SSE stream, so it answers GET with 405. Use POST for JSON-RPC; compliant clients do this automatically.
• A tool returns isError — tools return a structured payload with a stable code (for example VERSION_CONFLICT, INVALID_INPUT, NOT_FOUND) instead of throwing. Read the code to decide how to retry; for VERSION_CONFLICT, re-read the item and retry without a stale expected_version.
• A tool or field looks different from this page — the live tools/list response is authoritative. Fetch it and trust it over the prose here.

Still stuck? Email contact@wspc.ai.

Recurring rule 的 assignee_status 為 valid、not_member 或 unknown，todo_rule_get 也會回傳。後兩者暫停產生與重建 occurrences，保留既有 Todos。建立時指定非成員會回傳 INVALID_ASSIGNEE；membership 驗證失敗則回傳 ASSIGNEE_CHECK_UNAVAILABLE，不建立 rule。MCP 沒有修改 rule assignee 的 input。