Model Context Protocol (MCP)

Verbinde KI-Assistenten mit SNotes über den offiziellen Model Context Protocol (MCP) Server. Erfahre alles zu Streamable HTTP, OAuth und Claude-Integration.

The Model Context Protocol (MCP) is an open standard developed by Anthropic that enables large language models (LLMs) and AI agents to discover, query, and invoke tools against private data sources safely and reliably.

SNotes provides a first-class, official MCP server running directly on our European infrastructure.

Why MCP for Notes?

Instead of copy-pasting notes or relying on unreliable browser extensions, MCP allows AI assistants like Claude Desktop, Cursor, Zed, and autonomous coding agents to:

Search and read your notes, checklists, and reference materials in real-time.
Automatically capture summaries, action items, and task lists into your SNotes account.
Organize items into collections and manage todo checkboxes during conversational workflows.
Keep data secure with strictly scoped permissions and revocation capabilities.

Server Architecture & Transport

SNotes implements the Streamable HTTP transport (JSON-RPC 2.0 over HTTP POST).

┌─────────────────────────┐          JSON-RPC 2.0 (Streamable HTTP)         ┌─────────────────────────┐
│       AI Client         │ ──────────────────────────────────────────────> │    SNotes MCP Server    │
│  (Claude, Cursor, Zed)  │ <────────────────────────────────────────────── │   https://mcp.snotes.io │
└─────────────────────────┘      Authorization: Bearer mcpat_...            └─────────────────────────┘

Key Endpoints

Endpoint	Method	Purpose
`https://api.snotes.io/v1/mcp`	`POST`	MCP JSON-RPC 2.0 transport endpoint (`tools/list`, `tools/call`, etc.).
`https://api.snotes.io/v1/mcp/token`	`POST`	OAuth token endpoint (`client_credentials` grant exchange).
`https://api.snotes.io/v1/mcp/authorize`	`GET`	OAuth authorization code endpoint (for browser-based agent flows).
`https://api.snotes.io/.well-known/oauth-protected-resource/v1/mcp`	`GET`	RFC 9728 discovery metadata for MCP clients.
`https://api.snotes.io/.well-known/oauth-authorization-server`	`GET`	RFC 8414 OAuth authorization server metadata.

Context-Optimized Payloads

A major challenge with AI tool calling is token consumption. When an LLM reads tool responses, every byte of JSON consumes context window tokens and latency.

The SNotes MCP server automatically formats note outputs into compact representations:

Strips bulky image renditions and thumbhashes that models cannot interpret.
Preserves titles, body text, ordered checkbox items, and attachment transcription text.
Formats structured pages so models can easily browse and paginate through your notes.

Security & Scoping

OAuth Isolation: MCP access uses distinct MCP client credentials (sn_mcp_...) and access tokens (mcpat_...), separating AI access from personal REST tokens (sn_live_...).
Account Scoping: Tools strictly access only notes and collections belonging to the authenticated account.
Revocation: You can revoke an MCP client at any time in Settings → MCP Clients without invalidating your other API tokens or active sessions.