Skip to main content
Agent Keys provide secure, token-based authentication for AI agents to access your Commons workspaces through the Model Context Protocol (MCP). Each key can access multiple workspaces based on the permissions you configure.

​
Creating an Agent Key

Create an Agent Key from the management accordion on your dashboard. Select which workspaces it can access and set an expiration date (90 days by default). The key is displayed only once — copy it immediately and store it securely. If lost, you’ll need to regenerate it. Creating an Agent Key

​
Connecting Your Agent

After creating your Agent Key, you can use it to connect to Commons from any agent compatible with MCP. That includes anything from Claude Desktop to Cline to FLUJO. You can see more clients here. Below are guides for some of the most common MCP clients. Consult your client’s documentation for the most up-to-date connection method. Connection details are in the General MCP Clients section below.
Open Cursor Settings → Tools & MCPs, then click “New MCP Server” or edit your mcp.json file directly. Add this configuration:
{
  "commons": {
    "url": "https://api.capacitive.ai",
    "headers": {
      "Authorization": "Bearer YOUR_AGENT_KEY_HERE",
      "Accept": "application/json, text/event-stream"
    }
  }
}
Replace YOUR_AGENT_KEY_HERE with your actual Agent Key.
Use the Claude Code CLI to add the Commons MCP server:
claude mcp add --transport http commons https://api.capacitive.ai \
  --header "Authorization: Bearer YOUR_AGENT_KEY_HERE" \
  --header "Accept: application/json, text/event-stream"
Replace YOUR_AGENT_KEY_HERE with your actual Agent Key.Other useful commands:
  • List all MCP servers: claude mcp list
  • Check server status (within Claude Code): /mcp
  • Remove the server: claude mcp remove commons
For the most up-to-date documentation, visit Claude Code MCP Docs.
You can connect to our MCP server from any MCP-compatible AI client using these details:
  • Server URL: https://api.capacitive.ai
  • Transport Type: HTTP
  • Authentication Method: Bearer Token
Required headers:
Authorization: Bearer YOUR_AGENT_KEY_HERE
Accept: application/json, text/event-stream
See the Model Context Protocol’s official guide for more details on connecting to remote MCP servers.
Agent Keys can also be used to access Commons programmatically via our REST API. This is useful for custom integrations, scripts, workflows, or applications that need to interact with your workspaces.Base URL
https://api.capacitive.ai/v1
Authentication
Authorization: Bearer YOUR_AGENT_KEY_HERE

​
GET /api/manifest

DescriptionRetrieves a comprehensive manifest of all resources (integrations, files, and webpages) across all workspaces that the Agent Key has access to.Response includes:
  • List of accessible workspaces
  • Connected integrations per workspace
  • Uploaded files with metadata
  • Added webpages with status
Example
curl https://api.capacitive.ai/v1/api/manifest \
  -H "Authorization: Bearer YOUR_AGENT_KEY_HERE"

​
POST /api/search

DescriptionSearches across workspace data (apps, files, webpages) and returns ranked results with scores and metadata.Input
ParameterTypeDefaultDescription
querystring—Natural language search query (required)
source_typesstring"all"”all” or comma-separated like “app,file,webpage”
integration_idsstring""Comma-separated UUIDs for specific integrations
limitnumber10Maximum results per source type
Example
curl -X POST https://api.capacitive.ai/v1/api/search \
  -H "Authorization: Bearer YOUR_AGENT_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "recent pull requests",
    "source_types": "app",
    "limit": 10
  }'
Important Notes
  • API responses may take 10-45 seconds depending on query complexity. Configure your client timeout to 90+ seconds.
  • The operate tool is not exposed via REST API due to its approval and clarification requirements. Use MCP for full tool access.
  • All API requests are logged and auditable through your workspace activity logs.

​
Key Management

You can edit an Agent Key’s name and description from its detail page using the “Edit Settings” button. If you need to rotate a key, use “Regenerate Key” to create a new key with a new prefix. To permanently remove access, use “Delete Key” to revoke it. Both regeneration and deletion cannot be undone.