Capacities MCP Enhanced

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 newCapacities API 2.0with 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.

- ✍️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.

- Node.js 20+ or Bun 1.3+
- One or more personal API keys from the new Capacities API with the permissions you need

Configure your MCP client to use the Capacities MCP server:

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

{ "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" } } } }

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

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

search_objectsis title-only discovery. Uselist_objectswhen you already know a structure, tag UUID, or collection UUID and need membership listing; follownextCursorwhilehasMoreis true, then pass selected object IDs toget_objectfor full content.

upload_filesaccepts 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 optionalapiTokenargument on all tools. It overridesCAPACITIES_API_TOKENfor that call and accepts the same key-pool syntax.

CAPACITIES_API_TOKENand the per-callapiTokenoption 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.

On429, 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.

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 nativeAbortSignalcancellation, explicit per-part progress, pooled-key failover, and independent SDK readback verification.

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

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

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

Live API tests are available throughbun run test:livewhen a dedicated test token is configured.

- Capacities API 2.0 Developer Portal
- Capacities API 2.0 announcement
- Model Context Protocol

Sync Calendars, Scheduling Links, AI Executive Scheduling Assistant, Unified Calendar