MCP servers

MCP (Model Context Protocol) servers expose tools the agent can call. You add them from Settings > MCP or a project's MCP tab. Vixl speaks stdio, HTTP, and SSE. Config is mcp.json. Secrets stay in the OS keychain, never in that file. The file shape is on mcp.json.

Personal vs project

Settings > MCP writes the personal ~/.vixl/mcp.json. A project's MCP tab writes <repo>/.vixl/mcp.json. Same UI, different file. Paths are listed on .vixl layout.

A project server with the same id replaces the personal one (scope overridden). Inputs merge by id; the project value wins. The managed CodeGraph id codegraph is stripped from user lists and is not in the chat picker. Do not add it here; see Code graphs.

Home chats (Home in the composer) only see personal servers. Project chats see the merged set. A project whose folder is your user home directory is personal only: project MCP reads are empty and project MCP writes are refused. The chat MCP picker toggles enabled on the existing personal or project entry. There is no separate per-chat MCP list.

Add a server

  1. Open Settings > MCP, or a project's MCP tab.
  2. Choose Add server.
  3. Set a server id and a transport: stdio, http, or sse.
  4. Fill the transport fields.
  5. Save. That writes this scope's mcp.json and any new secrets to the keychain.

stdio

Command defaults to npx. It must be a PATH basename, not a filesystem path. Allowed names, env overlay rules, and envFile are on mcp.json. Args are comma-separated in the form and stored as a list. Env rows become ${input:KEY} secrets.

A project stdio server starts in that project's folder, even when Vixl itself was started somewhere else, so relative args resolve against the repo. If the project folder is missing, start fails. Personal servers are not given a project working directory.

HTTP and SSE

URL is required. auth is none, headers, or oauth. Use none for a public server, headers for static header auth, and oauth for browser OAuth. Header rows are secrets. For a bearer token, set auth to headers and Authorization to Bearer ${input:Authorization}.

URL policy, omitted-auth inference, and OAuth object fields are on mcp.json.

Trust

Start or enable may ask you to trust the server. Untrusted servers cannot start or be called. Trust is a fingerprint of the command plus args for stdio, or of the type plus URL for HTTP and SSE. Changing those requires trust again. Header and env changes do not.

This session stays in memory until you quit. This workspace writes project settings.json agent.mcp.trust[] with scope: "workspace" (falls back to personal always if there is no project). Always writes personal agent.mcp.trust[] with scope: "always". Never writes personal scope: "never" and blocks start. Personal never wins over a project grant on merge.

The prompt warns that the server can run code on your machine (for example via npx or uvx). If the agent calls an untrusted server, the tool error says to open Settings > MCP and start it to grant trust.

Trust does not skip permission gates. call_mcp_tool still goes through Ask / Allowlist / Bypass as mcp.call.

Inputs and secrets

Declared inputs and OAuth tokens store in the same OS keychain vault as provider keys. Template names and key formats are on mcp.json. The vault itself is on Providers. Missing inputs at start leave the server waiting for secrets.

OAuth

HTTP and SSE servers can use browser OAuth:

  1. Start the server.
  2. Grant trust if asked.
  3. Use Log in when the server needs auth.
  4. Confirm the authorization-server origin if prompted.
  5. Complete OAuth in the browser. Tokens land in the keychain.

Log out clears secrets and the HTTP session. Cancel sign in stops an in-flight login. In chat, auth can surface as an MCP auth card.

What the agent sees

Enabled servers appear in the system prompt as a catalog of names and short tool descriptions. The agent loads full schemas on demand (get_mcp_tools / get_mcp_tool), then calls call_mcp_tool. That is progressive discovery. Ask, Plan, Agent, and Orchestrator all include those tools.