Quick Start

Get up and running with CAPA in minutes. This guide will walk you through setting up your first CAPA project with a simple web research capability.

Step 1: Initialize

Navigate to your project directory and initialize CAPA:

cd your-project
capa init

This creates a capabilities.yaml file where you define your agent's tools and skills.

Step 2: Define Capabilities

Here's a minimal example with web search. Edit your capabilities.yaml:

providers:
  - cursor

options:
  toolExposure: on-demand

skills:
  - id: web-researcher
    type: inline
    def:
      content: |
        ---
        name: web-researcher
        description: Search the web for information
        ---
        Use the brave_search tool to find current information online.
    requires:
      - brave_search

servers:
  - id: brave
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-brave-search
      env:
        BRAVE_API_KEY: ${BraveApiKey}

tools:
  - id: brave_search
    type: mcp
    def:
      server: "@brave"
      tool: brave_web_search

Note: We're using toolExposure: on-demand to minimize context window usage. You can also use expose-all if you prefer all tools to be immediately visible.

Step 3: Install

Run the install command:

capa install

CAPA will:

  • Install skills to your client (e.g., .cursor/skills/)
  • Start the CAPA server
  • Prompt for credentials if needed (opens a web UI)
  • Display your MCP endpoint URL

Step 4: Configure Your MCP Client

Good news! capa install automatically registers with supported clients (Cursor, Claude Desktop).

If you need to verify or manually configure, the entry in .cursor/mcp.json looks like:

{
  "mcpServers": {
    "capa-your-project-id": {
      "url": "http://localhost:5912/your-project-id/mcp"
    }
  }
}

Note the key format is capa-${projectId}, allowing multiple CAPA projects in the same client.

Step 5: Use It

With on-demand mode, the agent sees two meta-tools: setup_tools and call_tool.

First, activate the skill:

setup_tools({"skills": ["web-researcher"]})

CAPA returns the available tools with their full schemas:

{
  "success": true,
  "message": "Activated 1 skill(s) with 1 tool(s)",
  "skills": ["web-researcher"],
  "tools": [
    {
      "name": "brave_search",
      "description": "Search the web using Brave Search",
      "inputSchema": { /* parameters */ }
    }
  ]
}

Then, invoke any activated tool:

call_tool({
  "name": "brave_search",
  "data": {
    "query": "latest AI developments"
  }
})

The agent's context stays minimal (only 2 meta-tools) until tools are actually needed.

What's Next?