Skip to content
CAPA CAPA capa

Servers (MCP)

Servers are MCP backends capa can start or proxy. Declare them under servers, choose which of their tools to expose (all of them by default), then run capa install.

Local (subprocess)

Section titled “Local (subprocess)”
servers:
  - id: brave
    type: mcp
    description: Brave Search MCP
    def:
      cmd: npx
      args: ['-y', '@modelcontextprotocol/server-brave-search']
      env:
        BRAVE_API_KEY: ${BraveApiKey}

capa expands ${VarName} at install time from the credential store or a .env via capa install -e. env and headers values can also be fromEnv, fromCommand, or fromFile objects resolved on demand. See Credentials.

Remote (HTTP)

Section titled “Remote (HTTP)”
servers:
  - id: company-mcp
    type: mcp
    def:
      url: https://mcp.example.com/sse
      headers:
        Authorization: Bearer ${CompanyMcpToken}
      # tlsSkipVerify: true   # only for trusted self-signed lab endpoints
OptionWhen to use
urlRemote MCP HTTP/SSE endpoint
headersAuth or custom headers (prefer ${VarName})
tlsSkipVerifySkip TLS verification for that server (lab/self-signed only). Ignored unless the capa server runs with CAPA_ALLOW_TLS_SKIP_VERIFY=1; CAPA_DISALLOW_TLS_SKIP_VERIFY=1 refuses it regardless

If you set an Authorization header, capa skips its OAuth2 probe for that server. Otherwise, remote servers that require OAuth can be completed from the Web UI during install or from the project’s server/OAuth screens.

Choose exposed tools

Section titled “Choose exposed tools”

By default a server exposes every tool it advertises; each becomes a capa tool under its remote name (for example brave.brave_web_search). Narrow that with expose:

servers:
  - id: github
    type: mcp
    expose: exactly          # all (default) | except | exactly | none
    tools: [create_issue, search_issues]   # remote tool names
    def:
      url: https://example.com/mcp
exposeResult
allEvery advertised tool (default)
exceptEverything except the names in tools
exactlyOnly the names in tools
noneNothing, unless you declare tools: entries yourself

tools is required with except and exactly, and rejected otherwise. capa add --server accepts the same choice as --expose <mode> plus --tools a,b. Plugin servers take it under plugins[].servers.<key> alongside as.

See Tool exposure for how exposed tools interact with skills and modes.

Wire tools by hand

Section titled “Wire tools by hand”

Declare tools: entries when you want your own ids, defaults, or a formatter:

tools:
  - id: search
    type: mcp
    def:
      server: '@brave'
      tool: brave_web_search

Once any tools: entry points at a server, those entries are the whole set for that server and its expose is ignored. Skills reference MCP tools as @brave.search. Run them with capa sh after install (for example capa sh brave search --help).

  1. Add the server block to capabilities.yaml.
  2. Keep the default expose: all, narrow it with except / exactly, or declare tools that point at @server-id.
  3. Put secrets in ${VarName} placeholders.
  4. Run capa install (and capa restart if you changed cmd, args, or env).
Section titled “Related”