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.

🚀 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