MCP Server

Memo runs a Model Context Protocol server at:

https://memo.matters.ai/api/mcp

Any MCP-aware client — claude.ai's "Add custom MCP", the Claude CLI, Cursor, VS Code agents, or your own scripts — can drive the same tool surface a memo owner uses by hand. Thirteen tools cover the whole owner API: project CRUD, file CRUD, publish, link CRUD, visit reads, and visitor URL resolution.

Transport#

Streamable HTTP (the modern MCP transport). One request/response per HTTP round-trip; no long-poll, no SSE, no session handshake — the same shape works in browser fetch, Node, curl, and serverless functions.

Protocol version header: MCP-Protocol-Version: 2025-06-18.

Auth#

Two bearer formats, both resolved through one helper (src/lib/auth/bearer.ts). Both surface the same tool capabilities; they just differ in how they're issued and which audit-log actor tag they get.

Both are sha256-hashed before storage (raw never sits in the DB), checked timing-safely on every request, and rate-limited to 60 calls/minute per (bearerId, IP) pair via Upstash sliding window.

PAT auth — for scripts and the local Claude CLI#

curl -X POST https://memo.matters.ai/api/mcp \
  -H "Authorization: Bearer mp_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

PATs:

• Are scope-limited at create time (projects:read|write, links:read|write, visits:read).
• Show the raw value exactly once at create time. The DB holds only the sha256.
• Have optional expiry (1–1825 days).
• Are individually revocable from the UI; revocation takes effect on the next request.
• Track last_used_at for inactivity audit.

OAuth 2.0 + PKCE — for claude.ai's "Add custom MCP"#

Memo speaks the full OAuth 2.0 Authorization Code + PKCE flow with Dynamic Client Registration (RFC 7591). When you point claude.ai at https://memo.matters.ai/api/mcp:

1. claude.ai hits /api/mcp with no bearer → memo returns 401 with a WWW-Authenticate: Bearer realm="memo", resource_metadata="…/.well-known/oauth-protected-resource" header.
2. claude.ai fetches the resource-metadata URL → learns the authorization server is https://memo.matters.ai.
3. claude.ai fetches /.well-known/oauth-authorization-server → gets authorize, token, revoke, and register URLs.
4. claude.ai POSTs to /oauth/register with its client_name, redirect_uris, etc. — memo writes a new row in oauth_clients and returns a client_id.
5. claude.ai opens /oauth/authorize?client_id=…&redirect_uri=…&scope=…&code_challenge=…&code_challenge_method=S256&state=… in your browser.
6. You sign into Clerk (if not already), see the consent screen rendered by authorize.astro, tick scopes, hit Authorize.
7. memo POSTs to /oauth/authorize/grant → mints a one-shot 10-minute code in oauth_authorization_codes, 303s back to claude.ai's redirect_uri?code=…&state=….
8. claude.ai POSTs the code + code_verifier to /oauth/token → memo verifies PKCE, marks the code consumed, mints an access token (ma_…, 1h TTL) + refresh token (mr_…, 30d TTL, single-use, rotated on every refresh).
9. claude.ai stores both, hits /api/mcp with the access token as a bearer, and we're off.

All four OAuth tables on memo's side (oauth_clients, oauth_authorization_codes, oauth_access_tokens, oauth_refresh_tokens) are documented in Data Model.

Discovery endpoints#

The 39 tools#

v3 added 26 tools on top of v2's 13. Claude now has full owner-account power: every action available in the owner UI is wired to a matching MCP tool.

Project lifecycle (v2 + v3)#

Every tool checks the calling bearer's scopes before executing and writes an audit_logs row with the action + actor tag on state changes.

v3 — full lifecycle parity#

The full JSON Schema for every tool is returned by tools/list. We don't embed it here so this doc never drifts from the source of truth — query the server directly.

Audit + revocation#

Every state-changing tool writes an audit_logs row:

{
  "actor_user_id": "<owner uuid>",
  "action":        "project.publish",
  "target_type":   "version",
  "target_id":     "<version uuid>",
  "meta":          { "actor": "mcp_oauth:<access_token_id>", ... }
}

The actor field in meta is the only place that records which token did the thing, so query by meta->>'actor' to attribute a change to a specific PAT or OAuth connection.

Revocation flows:

• PAT: owner clicks Revoke at /u/<username>/settings/tokens. Token rows get revoked_at set; next /api/mcp request returns 401.
• OAuth: owner clicks Revoke at /u/<username>/settings/connections (or the client calls /oauth/revoke). Both the access token and every refresh token from the same client get revoked_at set in one transaction.

Worked example — claude.ai#

For copy-paste setup:

1. Sign into claude.ai and open Settings → Connectors → Add custom MCP.
2. Server URL: https://memo.matters.ai/api/mcp.
3. claude.ai pings the URL, sees the 401 + resource-metadata pointer, walks the discovery chain, registers itself via /oauth/register, and pops a new browser tab on memo's /oauth/authorize.
4. Sign into memo, pick the scopes you want claude.ai to have, click Authorize.
5. Tab closes, claude.ai is connected. You can now ask Claude things like "list my memo projects" or "in project <name>, create a file index.html with a yellow CTA hero" and it will call tools/list → tools/call list_projects / tools/call write_file / etc.
6. Revoke at any time from /<your-username>/settings/connections.

For copy-paste local development (no OAuth needed):

1. Visit /<your-username>/settings/tokens and mint a PAT with the scopes you want.

2. Drop it into ~/.claude/mcp.json:

   {
     "mcpServers": {
       "memo": {
         "url": "https://memo.matters.ai/api/mcp",
         "headers": { "Authorization": "Bearer mp_…" }
       }
     }
   }
   

3. Restart the Claude CLI / IDE agent and memo shows up under available servers.