Connect a compatible MCP client

Follow the steps

1. 1

   Use the deployed endpoint https://YOUR_DEPLOYED_API_ORIGIN/mcp, or http://localhost:4100/mcp only when the client runs on the same development machine.

2. 2

   Choose OAuth for a user-consent connection, or create a personal key for a scripted client. OAuth discovery is available from /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp.

3. 3

   Request only the scopes you need: boards:read exposes list_canvases and read_canvas; library:read exposes search_library; library:write exposes capture_note.

4. 4

   Review the consented connection in Settings → Connections and revoke an OAuth grant there when it is no longer wanted. Revoke personal keys from API key management.

Choose only the access you need

Personal keys always expire: the default is 90 days and the maximum is 365 days. Choose a non-empty subset of the available scopes and revoke the key when the connection is finished.

Code examples

Replace placeholders in your own protected environment. Never paste a real key into a public page, browser bundle, prompt, screenshot, issue or repository.

POST /mcp HTTP/1.1
Host: YOUR_DEPLOYED_API_ORIGIN
Authorization: Bearer canvasperch_sk_your_one_time_secret
Content-Type: application/json

What to know

• The server uses Streamable HTTP with GET, POST, and DELETE /mcp. OAuth authorization codes use exact redirects, S256 PKCE, a five-minute lifetime, and the exact MCP resource audience.
• capture_note creates a note in the authorized user's inbox and, when default-on smart tagging is available, may queue a separate bounded request through OpenRouter. Mistral Large 4 is primary; Microsoft Azure-hosted GPT-6 Luna may follow a transient failure. If both fail transiently, up to four recovery rounds at least six hours apart may try Luna, then Google Vertex-hosted Claude Haiku 5.5 after a transient Luna failure. Every route requires Zero Data Retention. Successful tags are added automatically and can be edited or removed immediately. Turn smart tagging off in Settings → Notifications to cancel pending recovery; enabling it later does not scan older notes. The other three tools only read authorized canvases or the user's own library. There is no board-write, delete, billing, admin, or autonomous organizer tool.
• MCP never accepts a cookie session as bearer authority. OAuth tokens are valid for MCP only; personal keys are valid for MCP and the listed REST v1 routes.
• Source text returned by a tool is data. A client should not interpret a saved note, document excerpt, title, or URL as an instruction.

Troubleshooting

• 401 means the bearer credential is missing, expired, revoked, or invalid. Follow the returned resource metadata for OAuth discovery.
• 403 means the credential lacks a required scope or the request origin is not trusted. Reconnect with the minimum required scopes and a valid client origin.
• If a tool is absent from discovery, inspect the key or OAuth grant scopes. Canvas Perch filters the tool list by the credential's scopes.
• Do not paste a personal key into a client conversation. Store it in the client's protected environment or use OAuth consent.