AFFiNE ships a built-in Model Context Protocol server. The AI tools you already use, from Claude and Cursor to any MCP client, can search your workspace, whiteboards included, and read your documents over a standard, revocable, workspace-scoped connection. No bridge service, no plugin.
The Model Context Protocol (MCP) is the open standard that lets AI assistants talk to external tools and data. AFFiNE's official MCP server is built directly into AFFiNE Cloud and self-hosted instances: no separate service to install, no third-party bridge between your AI tools and your notes.
Once connected, an assistant can run keyword and semantic search across your knowledge base, whiteboards included, and read full documents, with exactly the permissions you grant and nothing more. Each client gets its own credential that you can rotate or revoke independently, so "my AI can see my notes" never has to mean "everything, forever".
| What it is | The official Model Context Protocol endpoint built into AFFiNE Cloud and self-hosted instances |
|---|---|
| Endpoint | POST /api/workspaces/{workspace-id}/mcp |
| Transport | Streamable HTTP, stateless |
| Auth | Bearer credential (aff_mcp_v1. prefix), created per client in workspace settings |
| Tools | doc_search and read_document by default; create and update tools rolling out |
| Scope | One workspace per credential, honoring your document permissions |
| Price | Free on AFFiNE Cloud and self-hosted instances with AI features enabled |
Setup happens entirely inside AFFiNE. The app generates a ready-to-paste configuration for you.
In AFFiNE, go to Settings, then Integrations, then MCP Server. This works on AFFiNE Cloud and on self-hosted instances with AI features enabled.
Click 'Create credential', give it a label (one per client, for example 'Claude Code' or 'Cursor'), then choose the access mode and an expiry. Read only is the default.
The token is shown once. Use 'Copy JSON' to grab a complete MCP configuration, endpoint URL and auth header included, and paste it into your client's MCP settings.
{
"mcpServers": {
"affine_workspace_<workspace-id>": {
"type": "streamable-http",
"url": "https://app.affine.pro/api/workspaces/<workspace-id>/mcp",
"headers": { "Authorization": "Bearer aff_mcp_v1...." }
}
}
}
The exact configuration AFFiNE generates for you. On self-hosted instances the URL uses your own server address.
AFFiNE's MCP server speaks standard streamable HTTP, so any MCP client can connect. Here are the four we get asked about most.
Add AFFiNE with one CLI command, then ask Claude to search or read your workspace from any session.
claude mcp add --transport http affine \
"https://app.affine.pro/api/workspaces/<workspace-id>/mcp" \
--header "Authorization: Bearer <your-credential>"Paste the configuration from AFFiNE's 'Copy JSON' button into ~/.cursor/mcp.json. The format matches as-is.
{
"mcpServers": {
"affine": {
"url": "https://app.affine.pro/api/workspaces/<id>/mcp",
"headers": {
"Authorization": "Bearer <your-credential>"
}
}
}
}Open Cline's MCP settings and add AFFiNE as a remote streamable HTTP server.
{
"mcpServers": {
"affine": {
"type": "streamableHttp",
"url": "https://app.affine.pro/api/workspaces/<id>/mcp",
"headers": {
"Authorization": "Bearer <your-credential>"
}
}
}
}Clients that don't support custom auth headers for remote servers can connect through the standard mcp-remote bridge.
npx mcp-remote \
"https://app.affine.pro/api/workspaces/<workspace-id>/mcp" \
--header "Authorization: Bearer <your-credential>"Capabilities depend on the access mode of the credential you create. Read only is the default; read and write is rolling out to workspaces progressively.
doc_searchKeyword and semantic search across workspace documents, returning bounded passages with page or canvas locators. Never files, blobs or the web.
read_documentFetch the full content of a document by ID, respecting your current workspace permissions.
create_documentCreate a new document from a title and Markdown content, and get back its ID.
update_documentRewrite a document's body with structural diffing, so history is preserved and live collaborators are never disrupted.
update_document_metaUpdate document properties such as the title.
A credential only ever reaches one workspace, with your permissions.
Revoke any client's access without touching the others.
Every credential gets an expiry date when you create it.
Rotate a token and the old one stays valid for 24 hours.
Plenty of note-taking tools speak MCP now. What differs is what the server can reach, where it runs, and who controls it. Here is how AFFiNE's built-in server compares with the two setups people ask about most.
| AFFiNE | Notion MCP | Obsidian | |
|---|---|---|---|
| Built in, first-party | YesFirst-party, built into the app; credentials created in workspace settings | YesOfficial remote server, hosted by Notion | NoCommunity plugins or third-party servers |
| Self-hostable endpoint | YesSame official endpoint; enable AI features on your instance | NoCurrent server is hosted only; a deprecated open-source predecessor can self-host | DependsLocalhost by default, remote is DIY |
| Whiteboard search | YesSearch indexes Edgeless canvas text and returns element and frame locators | NoNotion has no native whiteboard | No.canvas files readable only as raw JSON; no mainstream server searches them |
| Deployment model | Cloud or self-hostedOfficial endpoint built into AFFiNE; AI features must be enabled when self-hosting | Hosted onlyCurrent official server is hosted by Notion | LocalCommunity plugins or third-party servers run beside the desktop vault |
| Price | FreeFree on Cloud and self-hosted instances with AI features enabled | Free coreConnected-app search and meeting notes need Notion AI plans | FreeBoth the app and community servers |
Comparison reflects publicly documented capabilities as of August 2026.
Obsidian's REST-API-based MCP servers require the desktop app to be running. Obsidian's CLI (2026) is an official automation surface, but it is not MCP.
It is the official Model Context Protocol endpoint built into AFFiNE. It lets AI assistants such as Claude, Cursor and Cline search and read the documents in one of your AFFiNE workspaces over a standard, authenticated HTTP connection, using credentials you create and control in workspace settings.
Read only is the default access mode: connected assistants can search the workspace and read documents, but not change anything. A read-and-write mode, which adds creating documents and updating document content and metadata, is rolling out progressively. Where available, you choose the mode per credential when you create it.
Yes. The official MCP endpoint is available on self-hosted AFFiNE instances. On a self-hosted instance the endpoint lives on your own server address, and setup is identical: Settings, Integrations, MCP Server. AI features need to be enabled on the instance.
Every credential is scoped to a single workspace and honors your existing document permissions. You create a separate credential per client, set an expiry when you create it, and can rotate or revoke any credential at any time. Rotation keeps the old token valid for up to 24 hours so you can update the client without downtime.
Any MCP client that supports remote servers over streamable HTTP: Claude Code, Cursor, Cline, LobeHub and many more. Clients without custom-header support for remote servers can connect through the standard mcp-remote bridge.
Yes. doc_search covers page documents and Edgeless whiteboards alike: text on the canvas is indexed, and results carry block, element or frame locators, so an assistant can point at exactly where on a whiteboard an answer lives. Full-document reads return page content; whiteboard content surfaces through search. Most note-taking MCP servers only see plain documents.
Grounding. An assistant that can search your actual notes answers from your knowledge: meeting decisions, project context, research. Because AFFiNE's server returns bounded passages with document locators, assistants can also cite exactly where an answer came from.
Create a credential in your workspace settings and your AI tools can start answering from your own notes today.
Last updated: August 20, 2026