Introduction to CAPA

CAPA is a capabilities manager for AI agents. You define skills and tools, manage credentials, browse third-party registries, and ship the result to agents like Cursor, Claude Code, Codex, OpenCode, GitHub Copilot, Gemini CLI, Windsurf, Roo, Cline, Continue, Goose, and many more.

CAPA project view showing installed plugins, configured providers, and the skills, tools, and servers panels.
The CAPA project view. Plugins, providers, and your full capability inventory in one place. The bar across the top tracks how many tools the agent currently sees versus how many it could pull in on demand.

The Challenge: Skills Without the Right Tools

Skills are only as useful as the tools they can reach. Most teams hit the same four problems:

  • Tool overload: MCP servers often come with dozens of tools, but you only need a handful. Managing each tool individually is tedious and clutters the agent's context.
  • Skill duplication: Reusing skills across projects typically means copying them. This creates maintenance nightmares when you need to update a skill.
  • Command complexity: The best tools are often CLI commands, but complex operations with variables and dependencies consume precious tokens and require manual setup.
  • Static configuration: Traditional setups lock you into a fixed set of tools, with no way for agents to adapt their capabilities.

The CAPA Solution

CAPA solves these by running a single MCP server that:

  • Exposes only required tools: List the skills you need in your capabilities file. CAPA exposes only the tools those skills require and keeps context clean.
  • Fetches skills on demand: Reference skills in your capabilities file and run capa install to fetch them from GitHub, GitLab, or local repositories. No copy-paste.
  • Simplifies command tools: Define CLI tools with variable substitution and automatic prerequisite setup using the init block. No token waste on manual operations.
  • Enables self-improvement: The capabilities file lives in your project, so agents can edit it to add new skills and tools as they learn what they're missing.

Key Benefits

Single Server, Selected Tools

CAPA creates one MCP server that exposes only the tools your skills require. No more managing dozens of individual tools from bloated MCP servers.

Skill Reusability

Reference skills from GitHub, GitLab, or local repositories in your capabilities file. Run capa install to fetch them. No duplication, just declarative configuration.

Command Tools Made Simple

Define CLI tools with variable substitution and automatic initialization. Complex command sequences become single tool calls, saving tokens and reducing errors.

Dynamic Capability Loading

Agents start with minimal tools and load capabilities on demand. In on-demand mode, agents use setup_tools to activate skills and call_tool to invoke any tool. Context stays clean until tools are actually needed.

Agent-Driven Evolution

The capabilities file lives in your project, so agents can edit it to add new skills and tools as they learn what they're missing. The agent's capabilities grow with the work.

Pluggable Registries

Browse and install skills and plugins from third-party registries: public marketplaces like skills.sh and the Cursor Marketplace, or private company catalogs. Each registry is a single TypeScript file you drop into ~/.capa/registries/.

Security

Block dangerous phrases and sanitize skill content before installation. Configure allowed character sets and blocked phrase lists to keep your agent's skills safe. Registry-supplied data is HTML-escaped and Markdown previews are DOMPurify-sanitized.

How It Works

CAPA sits between your MCP client and multiple tool sources, proxying calls and managing tool lifecycle:

┌─────────────┐
│ MCP Client  │  (e.g., Cursor)
└──────┬──────┘
       │ In on-demand mode:
       │ Sees: setup_tools(), call_tool()
       │ 
       │ In expose-all mode:
       │ Sees: all tools directly
       ↓
┌─────────────┐
│ CAPA Server │  Manages tool lifecycle
└──────┬──────┘
       │ Proxies to tool sources
       ├──→ MCP Server 1
       ├──→ MCP Server 2
       └──→ Command Tools

On-Demand Mode Workflow

  1. Initial state: Agent sees two meta-tools: setup_tools and call_tool
  2. Activate skills: Agent calls setup_tools({"skills": ["web-researcher"]}})
  3. Receive schemas: CAPA returns full tool schemas (name, description, parameters)
  4. Invoke tools: Agent calls call_tool({"name": "brave.search", "data": {"query": "..."}}"}"})
  5. Get results: CAPA executes the tool and returns results

Benefits

  • Context stays clean with only 2 meta-tools in system prompt (on-demand mode)
  • Agent chooses which capabilities to activate based on the task
  • No dependency on dynamic tool list notifications
  • Works with all MCP clients
  • Multiple skill profiles can coexist

Next Steps

Ready to get started? Check out the Installation guide or jump right into the Quick Start.