Servers

Servers in CAPA are MCP (Model Context Protocol) servers that provide tools to AI agents. They can be local subprocesses or remote HTTP servers.

Server Types

Local Server (Subprocess)

Run an MCP server as a subprocess managed by CAPA:

servers:
  - id: filesystem
    type: mcp
    def:
      cmd: npx
      args:
        - -y
        - "@modelcontextprotocol/server-filesystem"
        - /path/to/directory
      env:
        API_KEY: ${ApiKey}

{
  "servers": [
    {
      "id": "filesystem",
      "type": "mcp",
      "def": {
        "cmd": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/path/to/directory"
        ],
        "env": {
          "API_KEY": "${ApiKey}"
        }
      }
    }
  ]
}

Remote Server (HTTP)

Connect to an MCP server running remotely via HTTP:

servers:
  - id: remote-server
    type: mcp
    def:
      url: https://api.example.com/mcp
      headers:
        Authorization: Bearer ${Token}
        X-Custom-Header: value

{
  "servers": [
    {
      "id": "remote-server",
      "type": "mcp",
      "def": {
        "url": "https://api.example.com/mcp",
        "headers": {
          "Authorization": "Bearer ${Token}",
          "X-Custom-Header": "value"
        }
      }
    }
  ]
}

Server Definition Fields

For Local Servers

id: Unique identifier for the server
type: Always mcp
description: (optional) Human-readable description shown in capa sh
def.cmd: Command to run (e.g., npx, node, python)
def.args: Array of command arguments
def.env: Environment variables for the subprocess

For Remote Servers

id: Unique identifier for the server
type: Always mcp
description: (optional) Human-readable description shown in capa sh
def.url: HTTP endpoint URL
def.headers: HTTP headers to send with requests

Server Description

Add a description to a server to give it a human-readable label in capa sh. Without a description, the shell falls back to a generic "N tools available" summary.

servers:
  - id: atlassian
    type: mcp
    description: Access to Atlassian Confluence and Jira
    def:
      cmd: npx -y @modelcontextprotocol/server-atlassian
      env:
        ATLASSIAN_TOKEN: ${AtlassianToken}

{
  "servers": [
    {
      "id": "atlassian",
      "type": "mcp",
      "description": "Access to Atlassian Confluence and Jira",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-atlassian",
        "env": {
          "ATLASSIAN_TOKEN": "${AtlassianToken}"
        }
      }
    }
  ]
}

Result in capa sh:

Capa Shell - Available commands:

  atlassian   Access to Atlassian Confluence and Jira

Variable Substitution

Use ${VariableName} for sensitive values:

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

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

CAPA will prompt for these values during capa install. See Credentials for more details.

Popular MCP Servers

Brave Search

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

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

Filesystem

servers:
  - id: filesystem
    type: mcp
    def:
      cmd: npx
      args:
        - -y
        - "@modelcontextprotocol/server-filesystem"
        - /Users/username/projects

{
  "servers": [
    {
      "id": "filesystem",
      "type": "mcp",
      "def": {
        "cmd": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/Users/username/projects"
        ]
      }
    }
  ]
}

GitHub

servers:
  - id: github
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-github
      env:
        GITHUB_TOKEN: ${GitHubToken}

{
  "servers": [
    {
      "id": "github",
      "type": "mcp",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-github",
        "env": {
          "GITHUB_TOKEN": "${GitHubToken}"
        }
      }
    }
  ]
}

Server Health Monitoring

CAPA automatically monitors MCP server health:

Detects crashed servers
Automatically restarts failed servers
Logs server errors for debugging
Reports server status via capa status

Referencing Servers in Tools

When defining tools, reference servers using @server-id:

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

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

Best Practices

Use descriptive IDs: Name servers clearly (e.g., brave, filesystem)
Secure credentials: Always use variable substitution for API keys
Test commands: Verify server commands work independently before adding to CAPA
Check logs: Use ~/.capa/logs/ to debug server issues
Use npx for npm packages: Add -y flag to auto-accept package installations