Skip to content

Managed vs passthrough

capa can apply your capabilities in two ways. Pick one path per workflow and stick to it so you do not mix managed MCP entries with native-only writes.

Comparison

	Managed (`capa install`)	Passthrough (`--passthrough`)
Source	`capabilities.yaml` / `.json`	Same file for `capa install --passthrough`, or `capa add --passthrough` writing native files
Provider files	Yes — skills, MCP client config, rules, hooks, agents blocks, and related managed artifacts	Yes — provider-native files only
capa server / MCP proxy	Yes — install starts and uses the local capa server	No — no capa server or proxy management on this path
Lockfile	Writes / updates `capabilities.lock` with pinned refs	Focus is native file writes; not the managed server/proxy path
Secrets	Web UI prompts or `-e .env`; stored in `~/.capa/capa.db`	Expand `${VarName}` from the environment / `-e` when writing native config; no capa proxy
Typical goal	One declarative file, shared tooling, `capa sh`, tool exposure modes	Drop skills/plugins/MCP into the provider’s own layout without running capa’s gateway

When to use managed

Use managed install when you want capa to own the loop:

Declare everything in the capabilities file and re-apply with capa install.
Run tools through capa’s MCP proxy or capa sh.
Use options.toolExposure, credentials in ~/.capa/capa.db, and the lockfile/cache pipeline.
Keep multiple providers in sync from one file.

capa install
capa install -e          # load .env instead of the credential web UI
capa install -p cursor   # single provider

When to use passthrough

Use --passthrough when you only need native provider files and do not want capa to manage a server or MCP proxy for that install/add:

capa install --passthrough
capa add <source> --passthrough -p cursor

Passthrough is useful for one-off native installs, environments that forbid a local capa gateway, or workflows where the provider itself should own plugins and MCP entries.