Overview

Build your own app, agent, or bot and integrate it with a Capacities space by implementing a custom MCP client using the Model Context Protocol (MCP) open standard. We host a server that provides secure access to a selected Capacities space via OAuth 2.1 (including PKCE, Dynamic Client Registration, and refresh tokens).

Supported tools

You can connect the Capacities MCP server to all AI tools that support the MCP protocol and connection via oAuth.

• If you want to use an existing AI chat app (no custom development), see AI Chat Connectors.
• If you want to build your own integration, continue below.

Available tools

1. search

Searches across your space via keywords. Results include:

• Object ID
• Object title
• Object Type
• Properties and content snippet

Search uses both full text search and semantic search to find and rank the best results.

Example prompt: "Find all Painting objects related to Claude Monet."

2. getObjectContent

Retrieves all content and properties from a specific object in markdown format.

Example prompt: "Read my highlights on The Happiness Hypothesis in Capacities and summarize the most important concepts."

3. createObjectLink

Generates a valid URL to access a specific object.

Example prompt: "Give me a link to my Cheesecake recipe in Capacities."

4. saveToDailyNote

Stores text within today's daily note.

Example prompt: "Send your conclusions about why folder structures don't work to my Capacities daily note."

Build a custom MCP client

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:

1. Start from the MCP URL

This is the resource your token must be valid for.

• Canonical MCP resource URL: https://api.capacities.io/mcp
• Transport: Streamable HTTP on /mcp
• Do not configure Server-Sent Events (SSE) for Capacities MCP

2. Discover protected resource metadata (RFC 9728)

It tells you which authorization server to use.

• Fetch: https://api.capacities.io/.well-known/oauth-protected-resource/mcp
• Fallback: read WWW-Authenticate: Bearer resource_metadata="..."
• Store:
  • resource
  • authorization_servers

3. Discover authorization server metadata (RFC 8414)

You need endpoints and capabilities before auth starts.

• Fetch: https://api.capacities.io/.well-known/oauth-authorization-server
• Confirm:
  • authorization_endpoint
  • token_endpoint
  • registration_endpoint
  • code_challenge_methods_supported includes S256 (SHA-256)

4. Generate Proof Key for Code Exchange (PKCE) parameters

PKCE protects public clients from code interception.

Before redirect:

1. Generate high-entropy code_verifier
2. Derive code_challenge using SHA-256 (S256)
3. Generate random state
4. Store code_verifier and state securely until callback

5. Register the client dynamically (RFC 7591)

Dynamic Client Registration (DCR) gives your app a valid client_id; web-based (non-native) clients also receive a client_secret.

POST to registration_endpoint with:

1. client_name
2. redirect_uris
3. grant_types: authorization_code, refresh_token
4. response_types: code
5. token_endpoint_auth_method:
   • native desktop (custom URI scheme or loopback): none
   • web-based (non-native): client_secret_basic or client_secret_post

Persist:

• client_id
• client_secret (web-based clients only, if returned)

6. Start authorization code flow

This is the user consent and authorization step.

Redirect users to authorization_endpoint with:

1. response_type=code
2. client_id
3. redirect_uri
4. scope (request only needed scopes: mcp:read, mcp:write)
5. state
6. code_challenge
7. code_challenge_method=S256
8. resource=https://api.capacities.io/mcp

7. Handle OAuth callback safely

Callback validation prevents Cross-Site Request Forgery (CSRF) and flow confusion.

On callback:

1. Validate state exactly
2. Read code
3. If error exists, stop and surface provider error

8. Exchange code for tokens

This returns the access token used for MCP calls.

POST to token_endpoint with:

1. grant_type=authorization_code
2. code
3. redirect_uri
4. code_verifier
5. client_id
6. client_secret (non-native/web-based clients only)

Persist securely:

• access_token
• refresh_token
• expiry metadata

9. Call MCP with bearer auth

Tokens are sent as standard OAuth bearer credentials.

• Header: Authorization: Bearer <access_token>
• Use Streamable HTTP transport

10. Implement refresh token handling

Refresh keeps sessions working without constant re-login.

Before token expiry:

1. Call token endpoint with grant_type=refresh_token
2. Save new refresh token if rotation returns one
3. On invalid_grant, require full re-auth

11. Follow security baseline

OAuth integrations fail safely only when these baseline controls are in place.

1. Use Hypertext Transfer Protocol Secure (HTTPS) in production
2. Validate callback state on every auth response
3. Store tokens in secure backend storage or OS keystore
4. Request minimum scopes needed
5. Treat refresh tokens as long-lived credentials

Redirect URI allowlisting (required)

To register your client, email [email protected] with:

1. A brief description of your project/client (include your public repository, if available).
2. The specific Redirect URI(s) you want us to authorize.
3. Whether your integration is web-based or native desktop (custom URI scheme or loopback redirect).

Once our team has reviewed your request and updated our settings, we will notify you so you can complete your integration.

Roadmap for the Capacities MCP Server

The current version of the Capacities MCP Server only includes a small set of tools. We think this makes the MCP already very powerful:

• It can retrieve all content and give you answers based on your knowledge base.
• You can capture insights from an AI conversation and save them to your daily note.

Nevertheless, we see great potential in extending the MCP server capabilities.

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.

The Capacities MCP server will be developed in conjunction with our 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.

If the official MCP is not enough for your needs, you'll be able to derive your own MCP server from our Public API.