[{"data":1,"prerenderedAt":731},["ShallowReactive",2],{"/developer/model-context-protocol":3,"/developer/model-context-protocol-surround":722},{"id":4,"title":5,"body":6,"description":713,"extension":714,"links":715,"meta":716,"navigation":717,"path":718,"seo":719,"stem":720,"__hash__":721},"docs/4.developer/model-context-protocol.md","Model Context Protocol",{"type":7,"value":8,"toc":690},"minimark",[9,12,20,25,45,50,53,77,81,90,93,107,110,117,125,128,133,141,144,149,157,160,165,169,172,176,179,196,200,203,232,236,239,276,280,283,286,319,323,333,339,395,398,409,413,416,421,467,471,474,477,497,501,504,508,536,539,553,557,560,571,575,578,581,599,603,606,626,630,637,644,655,658,662,665,673,676,679,687],[10,11],"capacities-pro-label",{},[13,14,16],"tip",{"title":15},"MCP Beta",[17,18,19],"p",{},"The current version of our Model Context Protocol is experimental. It is in Beta and is subject to change. You can expect more functionality to be added over time.",[21,22,24],"h2",{"id":23},"overview","Overview",[17,26,27,28,32,33,40,41,44],{},"Build your own app, agent, or bot and integrate it with a Capacities space by implementing a ",[29,30,31],"strong",{},"custom MCP client"," using the ",[34,35,39],"a",{"href":36,"rel":37},"https://modelcontextprotocol.io/introduction",[38],"nofollow","Model Context Protocol (MCP)"," open standard.\nWe host a server that provides secure access to a selected Capacities space via ",[29,42,43],{},"OAuth 2.1"," (including PKCE, Dynamic Client Registration, and refresh tokens).",[46,47,49],"h3",{"id":48},"supported-tools","Supported tools",[17,51,52],{},"You can connect the Capacities MCP server to all AI tools that support the MCP protocol and connection via oAuth.",[54,55,56,71],"ul",{},[57,58,59,60,63,64,70],"li",{},"If you want to ",[29,61,62],{},"use an existing AI chat app"," (no custom development), see ",[29,65,66],{},[34,67,69],{"href":68},"/reference/ai-chat-connectors","AI Chat Connectors",".",[57,72,59,73,76],{},[29,74,75],{},"build your own integration",", continue below.",[21,78,80],{"id":79},"available-tools","Available tools",[82,83,84],"ol",{},[57,85,86],{},[87,88,89],"code",{},"search",[17,91,92],{},"Searches across your space via keywords. Results include:",[54,94,95,98,101,104],{},[57,96,97],{},"Object ID",[57,99,100],{},"Object title",[57,102,103],{},"Object Type",[57,105,106],{},"Properties and content snippet",[17,108,109],{},"Search uses both full text search and semantic search to find and rank the best results.",[17,111,112,113],{},"Example prompt: ",[114,115,116],"em",{},"\"Find all Painting objects related to Claude Monet.\"",[82,118,120],{"start":119},2,[57,121,122],{},[87,123,124],{},"getObjectContent",[17,126,127],{},"Retrieves all content and properties from a specific object in markdown format.",[17,129,112,130],{},[114,131,132],{},"\"Read my highlights on The Happiness Hypothesis in Capacities and summarize the most important concepts.\"",[82,134,136],{"start":135},3,[57,137,138],{},[87,139,140],{},"createObjectLink",[17,142,143],{},"Generates a valid URL to access a specific object.",[17,145,112,146],{},[114,147,148],{},"\"Give me a link to my Cheesecake recipe in Capacities.\"",[82,150,152],{"start":151},4,[57,153,154],{},[87,155,156],{},"saveToDailyNote",[17,158,159],{},"Stores text within today's daily note.",[17,161,112,162],{},[114,163,164],{},"\"Send your conclusions about why folder structures don't work to my Capacities daily note.\"",[21,166,168],{"id":167},"build-a-custom-mcp-client","Build a custom MCP client",[17,170,171],{},"If you are building a custom implementation or a private tool and would like to integrate it with our MCP server, please follow this guide:",[46,173,175],{"id":174},"_1-start-from-the-mcp-url","1. Start from the MCP URL",[17,177,178],{},"This is the resource your token must be valid for.",[54,180,181,187,193],{},[57,182,183,184],{},"Canonical MCP resource URL: ",[87,185,186],{},"https://api.capacities.io/mcp",[57,188,189,190],{},"Transport: Streamable HTTP on ",[87,191,192],{},"/mcp",[57,194,195],{},"Do not configure Server-Sent Events (SSE) for Capacities MCP",[46,197,199],{"id":198},"_2-discover-protected-resource-metadata-rfc-9728","2. Discover protected resource metadata (RFC 9728)",[17,201,202],{},"It tells you which authorization server to use.",[54,204,205,211,217],{},[57,206,207,208],{},"Fetch: ",[87,209,210],{},"https://api.capacities.io/.well-known/oauth-protected-resource/mcp",[57,212,213,214],{},"Fallback: read ",[87,215,216],{},"WWW-Authenticate: Bearer resource_metadata=\"...\"",[57,218,219,220],{},"Store:\n",[54,221,222,227],{},[57,223,224],{},[87,225,226],{},"resource",[57,228,229],{},[87,230,231],{},"authorization_servers",[46,233,235],{"id":234},"_3-discover-authorization-server-metadata-rfc-8414","3. Discover authorization server metadata (RFC 8414)",[17,237,238],{},"You need endpoints and capabilities before auth starts.",[54,240,241,246],{},[57,242,207,243],{},[87,244,245],{},"https://api.capacities.io/.well-known/oauth-authorization-server",[57,247,248,249],{},"Confirm:\n",[54,250,251,256,261,266],{},[57,252,253],{},[87,254,255],{},"authorization_endpoint",[57,257,258],{},[87,259,260],{},"token_endpoint",[57,262,263],{},[87,264,265],{},"registration_endpoint",[57,267,268,271,272,275],{},[87,269,270],{},"code_challenge_methods_supported"," includes ",[87,273,274],{},"S256"," (SHA-256)",[46,277,279],{"id":278},"_4-generate-proof-key-for-code-exchange-pkce-parameters","4. Generate Proof Key for Code Exchange (PKCE) parameters",[17,281,282],{},"PKCE protects public clients from code interception.",[17,284,285],{},"Before redirect:",[82,287,288,294,304,310],{},[57,289,290,291],{},"Generate high-entropy ",[87,292,293],{},"code_verifier",[57,295,296,297,300,301,303],{},"Derive ",[87,298,299],{},"code_challenge"," using SHA-256 (",[87,302,274],{},")",[57,305,306,307],{},"Generate random ",[87,308,309],{},"state",[57,311,312,313,315,316,318],{},"Store ",[87,314,293],{}," and ",[87,317,309],{}," securely until callback",[46,320,322],{"id":321},"_5-register-the-client-dynamically-rfc-7591","5. Register the client dynamically (RFC 7591)",[17,324,325,326,329,330,70],{},"Dynamic Client Registration (DCR) gives your app a valid ",[87,327,328],{},"client_id","; web-based (non-native) clients also receive a ",[87,331,332],{},"client_secret",[17,334,335,336,338],{},"POST to ",[87,337,265],{}," with:",[82,340,341,346,351,364,371],{},[57,342,343],{},[87,344,345],{},"client_name",[57,347,348],{},[87,349,350],{},"redirect_uris",[57,352,353,356,357,360,361],{},[87,354,355],{},"grant_types",": ",[87,358,359],{},"authorization_code",", ",[87,362,363],{},"refresh_token",[57,365,366,356,369],{},[87,367,368],{},"response_types",[87,370,87],{},[57,372,373,376,377],{},[87,374,375],{},"token_endpoint_auth_method",":\n",[54,378,379,385],{},[57,380,381,382],{},"native desktop (custom URI scheme or loopback): ",[87,383,384],{},"none",[57,386,387,388,391,392],{},"web-based (non-native): ",[87,389,390],{},"client_secret_basic"," or ",[87,393,394],{},"client_secret_post",[17,396,397],{},"Persist:",[54,399,400,404],{},[57,401,402],{},[87,403,328],{},[57,405,406,408],{},[87,407,332],{}," (web-based clients only, if returned)",[46,410,412],{"id":411},"_6-start-authorization-code-flow","6. Start authorization code flow",[17,414,415],{},"This is the user consent and authorization step.",[17,417,418,419,338],{},"Redirect users to ",[87,420,255],{},[82,422,423,428,432,437,449,453,457,462],{},[57,424,425],{},[87,426,427],{},"response_type=code",[57,429,430],{},[87,431,328],{},[57,433,434],{},[87,435,436],{},"redirect_uri",[57,438,439,442,443,360,446,303],{},[87,440,441],{},"scope"," (request only needed scopes: ",[87,444,445],{},"mcp:read",[87,447,448],{},"mcp:write",[57,450,451],{},[87,452,309],{},[57,454,455],{},[87,456,299],{},[57,458,459],{},[87,460,461],{},"code_challenge_method=S256",[57,463,464],{},[87,465,466],{},"resource=https://api.capacities.io/mcp",[46,468,470],{"id":469},"_7-handle-oauth-callback-safely","7. Handle OAuth callback safely",[17,472,473],{},"Callback validation prevents Cross-Site Request Forgery (CSRF) and flow confusion.",[17,475,476],{},"On callback:",[82,478,479,485,490],{},[57,480,481,482,484],{},"Validate ",[87,483,309],{}," exactly",[57,486,487,488],{},"Read ",[87,489,87],{},[57,491,492,493,496],{},"If ",[87,494,495],{},"error"," exists, stop and surface provider error",[46,498,500],{"id":499},"_8-exchange-code-for-tokens","8. Exchange code for tokens",[17,502,503],{},"This returns the access token used for MCP calls.",[17,505,335,506,338],{},[87,507,260],{},[82,509,510,515,519,523,527,531],{},[57,511,512],{},[87,513,514],{},"grant_type=authorization_code",[57,516,517],{},[87,518,87],{},[57,520,521],{},[87,522,436],{},[57,524,525],{},[87,526,293],{},[57,528,529],{},[87,530,328],{},[57,532,533,535],{},[87,534,332],{}," (non-native/web-based clients only)",[17,537,538],{},"Persist securely:",[54,540,541,546,550],{},[57,542,543],{},[87,544,545],{},"access_token",[57,547,548],{},[87,549,363],{},[57,551,552],{},"expiry metadata",[46,554,556],{"id":555},"_9-call-mcp-with-bearer-auth","9. Call MCP with bearer auth",[17,558,559],{},"Tokens are sent as standard OAuth bearer credentials.",[54,561,562,568],{},[57,563,564,565],{},"Header: ",[87,566,567],{},"Authorization: Bearer \u003Caccess_token>",[57,569,570],{},"Use Streamable HTTP transport",[46,572,574],{"id":573},"_10-implement-refresh-token-handling","10. Implement refresh token handling",[17,576,577],{},"Refresh keeps sessions working without constant re-login.",[17,579,580],{},"Before token expiry:",[82,582,583,589,592],{},[57,584,585,586],{},"Call token endpoint with ",[87,587,588],{},"grant_type=refresh_token",[57,590,591],{},"Save new refresh token if rotation returns one",[57,593,594,595,598],{},"On ",[87,596,597],{},"invalid_grant",", require full re-auth",[46,600,602],{"id":601},"_11-follow-security-baseline","11. Follow security baseline",[17,604,605],{},"OAuth integrations fail safely only when these baseline controls are in place.",[82,607,608,611,617,620,623],{},[57,609,610],{},"Use Hypertext Transfer Protocol Secure (HTTPS) in production",[57,612,613,614,616],{},"Validate callback ",[87,615,309],{}," on every auth response",[57,618,619],{},"Store tokens in secure backend storage or OS keystore",[57,621,622],{},"Request minimum scopes needed",[57,624,625],{},"Treat refresh tokens as long-lived credentials",[46,627,629],{"id":628},"redirect-uri-allowlisting-required","Redirect URI allowlisting (required)",[631,632,634],"warning",{"title":633},"Authorizing Your Redirect URI",[17,635,636],{},"To maintain a secure environment for all users, we do not allow arbitrary redirect URIs. If you are developing a custom client, your application's Redirect URI must be manually verified by a member of our team before the OAuth flow will function.",[17,638,639,640,338],{},"To register your client, email ",[34,641,643],{"href":642},"mailto:team@capacities.io","team@capacities.io",[82,645,646,649,652],{},[57,647,648],{},"A brief description of your project/client (include your public repository, if available).",[57,650,651],{},"The specific Redirect URI(s) you want us to authorize.",[57,653,654],{},"Whether your integration is web-based or native desktop (custom URI scheme or loopback redirect).",[17,656,657],{},"Once our team has reviewed your request and updated our settings, we will notify you so you can complete your integration.",[21,659,661],{"id":660},"roadmap-for-the-capacities-mcp-server","Roadmap for the Capacities MCP Server",[17,663,664],{},"The current version of the Capacities MCP Server only includes a small set of tools. We think this makes the MCP already very powerful:",[54,666,667,670],{},[57,668,669],{},"It can retrieve all content and give you answers based on your knowledge base.",[57,671,672],{},"You can capture insights from an AI conversation and save them to your daily note.",[17,674,675],{},"Nevertheless, we see great potential in extending the MCP server capabilities.",[17,677,678],{},"We do not envision the MCP to be a tool to \"automate knowledge work\", but rather a tool to help you to be more productive and creative.",[17,680,681,682,686],{},"The Capacities MCP server will be developed in conjunction with our ",[34,683,685],{"href":684},"/developer/api","Public API",". But we'll fine-tune API routes for AI usage so the Capacities MCP server a powerful companion when working with AI so it simply works.",[17,688,689],{},"If the official MCP is not enough for your needs, you'll be able to derive your own MCP server from our Public API.",{"title":691,"searchDepth":692,"depth":119,"links":693},"",1,[694,697,698,712],{"id":23,"depth":119,"text":24,"children":695},[696],{"id":48,"depth":135,"text":49},{"id":79,"depth":119,"text":80},{"id":167,"depth":119,"text":168,"children":699},[700,701,702,703,704,705,706,707,708,709,710,711],{"id":174,"depth":135,"text":175},{"id":198,"depth":135,"text":199},{"id":234,"depth":135,"text":235},{"id":278,"depth":135,"text":279},{"id":321,"depth":135,"text":322},{"id":411,"depth":135,"text":412},{"id":469,"depth":135,"text":470},{"id":499,"depth":135,"text":500},{"id":555,"depth":135,"text":556},{"id":573,"depth":135,"text":574},{"id":601,"depth":135,"text":602},{"id":628,"depth":135,"text":629},{"id":660,"depth":119,"text":661},"Developer guide to build and integrate a custom MCP client with Capacities (OAuth 2.1, PKCE, Dynamic Client Registration, token refresh).","md",null,{},true,"/developer/model-context-protocol",{"title":5,"description":713},"4.developer/model-context-protocol","CkXxJoVadcD8yC3YoJPbGipwGSvtTZE__w4KKGFtp2k",[723,727],{"title":724,"path":725,"stem":726,"children":-1},"Contribute","/developer/contribute","4.developer/contribute",{"title":728,"path":729,"stem":730,"children":-1},"Responsible Disclosure Program","/developer/responsible-disclosure","4.developer/responsible-disclosure",1776250821702]