Introduction to CAPA

CAPA is a smart tool manager for AI agents that reduces context window bloat and gives agents control over their own toolset.

The Challenge: Skills Without the Right Tools

Skills are powerful, but useless without the right tools. Modern AI development faces several tool management challenges:

  • 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 addresses these challenges by creating a single, intelligent MCP server that:

  • Exposes only required tools: List the skills you need in your capabilities file. CAPA automatically exposes only the tools those skills require, keeping context clean.
  • Fetches skills on demand: Instead of duplicating skills, simply reference them in your capabilities file and run capa install to fetch them from GitHub, GitLab, or local repositories.
  • Simplifies command tools: Define command-line tools with variable substitution and automatic prerequisite setup using the init block—no token waste on manual operations.
  • Enables self-improvement: Because the capabilities file is part of your project, agents can edit it to add new skills and tools, creating a feedback loop for continuous improvement.

Key Benefits

Single Server, Selected Tools

CAPA creates one MCP server that exposes only the tools required by your skills. 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 simple 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, keeping context 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. Your agent's capabilities evolve through use, creating a powerful feedback loop.

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.

How It Works

CAPA acts as an intelligent proxy between your MCP client and multiple tool sources:

┌─────────────┐
│ 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.