AFFiNE’s workspace MCP endpoint lets compatible AI clients search your notes and whiteboard text and read documents using a revocable credential. Connect directly with Streamable HTTP and Bearer-header support, or use a local stdio bridge when your client supports one.
MCP is an open standard for connecting AI assistants to tools and data. AFFiNE includes a workspace endpoint on supported Cloud and self-hosted instances. Direct connections need Streamable HTTP and a custom Authorization header; a stdio-only desktop client needs a local bridge such as mcp-remote.
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 / read_document; READ_WRITE: development / canary |
| Scope | One workspace per credential, honoring your document permissions |
| Price | Free on AFFiNE Cloud and self-hosted instances with AI features enabled |
On AFFiNE Cloud or your own supported instance. Requires your workspace Bearer credential and honors document permissions. The tools below are the read-only defaults; availability depends on the deployment.
https://app.affine.pro/api/workspaces/{workspace-id}/mcpdoc_searchread_documentA separate read-only service for published AFFiNE blog articles and templates. No account or credential is needed. It cannot read your workspace or write documents; never send your workspace credential to this endpoint.
https://affine.pro/api/public/mcpsearch_public_contentread_public_contentCreate a workspace credential in AFFiNE, then configure the intended client using its own transport format.
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.
Copy the endpoint and credential from AFFiNE. The token is shown once. Use the matching client example below rather than assuming every client accepts the same JSON.
{
"mcpServers": {
"affine_workspace_<workspace-id>": {
"type": "streamable-http",
"url": "https://app.affine.pro/api/workspaces/<workspace-id>/mcp",
"headers": { "Authorization": "Bearer aff_mcp_v1...." }
}
}
}
AFFiNE’s generated connection format. Adapt it to your client; self-hosted instances use their own server address.
Check both transport and authentication support. Claude Code, Cursor and Cline accept remote HTTP connections with a Bearer header. A client that only accepts OAuth sign-in cannot use this manually provisioned credential through that flow. A local stdio bridge is an option only if the client can launch local processes.
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>"Add the URL and headers shown below to ~/.cursor/mcp.json. Use the endpoint and credential copied from your own workspace; client configuration formats differ.
{
"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>"
}
}
}
}For a client that can launch local stdio processes, this configuration runs the third-party mcp-remote bridge. Install a supported Node.js runtime and follow the bridge documentation. This is not a Claude web OAuth connector.
{
"mcpServers": {
"affine": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://app.affine.pro/api/workspaces/<workspace-id>/mcp",
"--header",
"Authorization:${AFFINE_MCP_AUTH}"
],
"env": {
"AFFINE_MCP_AUTH": "Bearer <your-credential>"
}
}
}
}Read only is the default. The implementation reviewed on October 26, 2026 restricts read-write credential creation and write tools to development or canary deployments. This does not establish stable Cloud availability. Check your instance’s access-mode settings and tools/list before relying on writes.
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_documentWhere enabled, create a document from a title and Markdown body. Database-block and image insertion are not supported by this tool.
update_documentWhere enabled, update the Markdown body using structural diffing. This does not change the title or support database-block or image updates.
update_document_metaWhere enabled, update a document’s title. Other metadata fields are not exposed by the inspected tool.
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.
After rotation, the old token works for up to 24 hours, or until its existing expiry if sooner. Revocation can end access earlier.
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. The implementation reviewed on October 26, 2026 restricts read-write credential creation and write tools to development or canary deployments. This does not establish stable Cloud availability. Check your instance’s access-mode settings and tools/list before relying on writes.
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.
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. After rotation, the old token works for up to 24 hours, or until its existing expiry if sooner. Revocation can end access earlier.
Check both transport and authentication support. Claude Code, Cursor and Cline accept remote HTTP connections with a Bearer header. A client that only accepts OAuth sign-in cannot use this manually provisioned credential through that flow. A local stdio bridge is an option only if the client can launch local processes.
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: October 26, 2026