MCP Extensions

MCP (Model Context Protocol) extensions let the AI Assistant call out to external tools — browser automation, ticket trackers, knowledge bases. They run on the local agent, not in the portal, so they have your filesystem context and your credentials.

Where to configure

Portal → Settings → MCP Extensions.

Each extension shows:

• Catalog name (e.g. playwright-browser, youtrack-mcp, github-mcp)
• Required agent mode (advisor, builder, operator)
• Status (installed, running, error)

Agent modes and MCP

MCP availability depends on the agent's mode (set under Agent Sandbox):

Mode	MCP allowed	Risk
advisor	none	low — read-only chat
builder	browser MCP + chat-safe extensions	medium
operator	full catalog incl. ops-grade and admin extensions	high

Operator mode is opt-in; the agent prompts for confirmation before enabling.

Allowed runtimes

The agent only spawns MCP servers from a whitelist of runtimes:

npx, node, python, python3, uvx

Anything else is rejected. Extensions are pinned to their package version in ~/.xyva/mcp-lock.json.

Recommended flow

1. Pick the lowest agent mode that fits your task — start in advisor.
2. Install only the MCP servers you actively need; each one widens the agent's surface.
3. For Builder/Operator modes, review the Agent Sandbox policy before enabling.
4. Inspect the MCP audit log under Settings → Agent Sandbox → Audit Log after each significant action.

Troubleshooting

Symptom	Fix
Extension stuck in installing	Check the agent terminal — install probably failed silently
Tool calls return 401	Re-authenticate in the extension config
runtime not allowed	The MCP server uses a runtime not on the whitelist; pick a different package

What to read next

• Agent Sandbox
• AI Provider Setup
• Feature Flags