Capacities MCP Enhanced — API 2.0 for AI Agents

The official MCP server sucks, it's time to make a new one.

Built for the new Capacities API 2.0 with native precise block level CRUD support.

Capacities MCP brings rich, read-write access to your knowledge base through one agent-friendly server. Agents can discover your object types, understand custom properties, create polished content, make precise edits, save web resources, and work with Daily Notes.

✨ Why Capacities MCP Enhanced

• ✍️ Markdown & structured block authoring — combine fast Markdown workflows with precise Capacities-native block editing in one server.

• 🧩 Full CRUD with Capacities API 2.0 — objects, custom properties, collections, blocks, web links, tasks, tags, and Daily Notes.

• 🤖 Designed for autonomous agents — live schema discovery, consistent responses, focused tools, and clear recovery information.

• 📤 Agent-friendly MCP file uploads — support multi-file and large-file uploads with built-in MCP progress reporting, streaming transfers, upload verification, and long-running job tracking.

• 🔑 API key pooling — distribute requests across multiple API keys, improve throughput under rate limits, and provide resilient API access for high-volume workloads.

• 🔒 Concurrency-safe object operations — same-object reads can run concurrently, while writes use an exclusive lock and automatically wait for active reads or other writes; different objects proceed concurrently.

• 🎨 Faithful rich content — headings, nested blocks, grids, toggles, tasks, links, entity references, colors, code, and math.

• 📚 Bundled best-practice skill — a complete agent operating guide is included, so a model can use the server correctly without already knowing Capacities.

Related MCP server: SpaceTraders MCP Server

🚀 Quick start

Requirements

• Node.js 20+ or Bun 1.3+

• One or more personal API keys from the new Capacities API with the permissions you need

Installation

Configure your MCP client to use the Capacities MCP server:

Generate a token in Capacities → Settings → Capacities API → Generate new token. New API tokens begin with cap-api-.
Configuring at least 3 tokens with same space and permissions is recommended to avoid rate-limit errors.

Claude Code

{
  "mcpServers": {
    "capacities": {
      "command": "npx",
      "args": ["--yes", "capacities-mcp-enhanced@latest"],
      "env": {
        "CAPACITIES_API_TOKEN": "cap-api-key-1,cap-api-key-2;cap-api-key-3"
      }
    }
  }
}

Hermes Agent

mcp_servers:
  capacities:
    command: "npx"
    args:
      - "--yes"
      - "capacities-mcp-enhanced@latest"
    env:
      CAPACITIES_API_TOKEN: "cap-api-key-1,cap-api-key-2;cap-api-key-3"
    supports_parallel_tool_calls: true

Install the bundled skills (Optional)

By installing the Capacities MCP Best Practices skill, your agent can learn the full workflow, strict content schemas, safe mutation patterns, rate-limit recovery, and common pitfalls.

npx skills add nyrest/capacities-mcp-enhanced

🧰 What agents can do

search_objects is title-only discovery. Use list_objects when you already know a structure, tag UUID, or collection UUID and need membership listing; follow nextCursor while hasMore is true, then pass selected object IDs to get_object for full content.

upload_files accepts absolute local file paths only; relative paths, directories, and empty files are rejected. Background upload jobs live only in the current MCP process and retain terminal status for a limited time.

Supported environment variables and configuration options

Per-call configuration is exposed through the optional apiToken argument on all tools. It overrides CAPACITIES_API_TOKEN for that call and accepts the same key-pool syntax.

⚙️ API key pool and rate limits

CAPACITIES_API_TOKEN and the per-call apiToken option accept multiple API keys separated by , or ;. Keys are selected with round-robin scheduling independently for each endpoint, skipping keys currently marked as rate-limited.

All keys in one pool must belong to the same space and have the same permissions. At least 3 keys are recommended; use separate MCP server instances for multiple spaces.

On 429, the pool immediately fails over to another key that is not rate limited. The error is returned only when all keys are rate limited. No waiting, exponential backoff, or cross-pool retry is performed.

🚅 Concurrency and safe writes

Reads for the same object can run concurrently. A mutation obtains an exclusive object lock, so it waits for active reads and other writes; reads arriving during a write wait as well. Operations for different objects proceed concurrently. This protects the full read → mutate → readback lifecycle against last-write-wins races. The Capacities SDK does not expose request cancellation/timeout configuration, so ordinary SDK-backed calls do not use an unsafe client-side timeout race. Multipart media upload is the sole direct-HTTP path: it retains native AbortSignal cancellation, explicit per-part progress, pooled-key failover, and independent SDK readback verification.

🛠️ Development

bun run lint
bun run typecheck
bun test
bun run build
bun run verify:tools

The final local release gate is:

npm run release:check
npm publish --dry-run --access public

npm publish --dry-run validates the package without publishing it. Actual publishing additionally requires an authenticated npm account.

Live API tests are available through bun run test:live when a dedicated test token is configured.

📚 Documentation

• Capacities API 2.0 Developer Portal

• Capacities API 2.0 announcement

• Model Context Protocol