Skip to content

Common issues

Match the symptom you see, then apply the fix. After config changes that affect the proxy, finish with capa install and often capa restart.

Symptom → fix

Symptom	Fix
Server won’t start / unhealthy	Run `capa status`. Check `~/.capa/logs/server.log`. Then `capa stop` and `capa start` (or `capa start -f` to watch logs).
Skills missing in the client	Run `capa clean` then `capa install`. Confirm skill dirs (e.g. `.cursor/skills/`) and MCP config (e.g. `.cursor/mcp.json`). Reload the client.
Credentials not prompting	Use exact `${VarName}` placeholders in the capabilities file. Ensure variables are referenced by servers/tools. Run `capa install` (web UI at the local server) or `capa install -e`. Try `capa restart`.
MCP / TLS: `SELF_SIGNED_CERT_IN_CHAIN`	For trusted internal servers only, set `tlsSkipVerify: true` on the server `def`, then `capa install` and `capa restart`.
Installation blocked: forbidden phrase	A skill hit `options.security.blockedPhrases`. Remove the phrase from the skill, or adjust/remove `blockedPhrases`, then `capa install` again.
Tool not found	MCP tools in `requires` need `@server_id.tool_id`. Command tools use the plain id. Confirm `capa status` and that the tool id matches the MCP server.
Stale remote skills / plugins	`capa install --no-cache`, or `capa cache clean` then `capa install`.
`capa wrap`: binary missing	Install the provider CLI and ensure it is on `PATH`. Wrap fails fast before creating a workspace.
Provider / interactive prompt in CI	Non-TTY cannot prompt. Pass `capa install -p <provider>` (e.g. `-p cursor`) explicitly.
MCP not registered in client config	Expected when no tools or subagents are configured. Add at least one tool or subagent, then reinstall.
Token auth errors at MCP startup	Ensure `Authorization` (or equivalent) is in `def.headers`. Re-set `${VarName}` via `capa install -e` or the web UI.

Quick commands

capa status
capa stop
capa start -f

capa clean
capa install
capa install --no-cache
capa cache clean

capa wrap cursor          # after fixing PATH
capa install -p cursor    # CI-safe provider

See also