MCP server setup

Veyyon can connect to third-party Model Context Protocol (MCP) servers so external tools and data sources become available to the agent. Register a server, choose a transport, authenticate, and fix the most common connection problems.

For an overview of what MCP does in Veyyon, see MCP. Engineering reference: docs/handbook/src/reference/mcp-config.md.

Where servers are configured

MCP servers are configured as JSON in mcp.json, not in config.yml:

There is no project scope: a repository’s own mcp.json, .mcp.json, or .veyyon/mcp.json is not read, because a checked-in file must not name a server the agent connects to. No /mcp subcommand takes a scope, and writing project or user as an argument is rejected with that reason rather than accepted, in a terminal and in a client alike.

Veyyon also discovers MCP entries from other tools’ user-level configs (Claude, Cursor, Codex, Gemini, OpenCode, Windsurf). The easiest way to add a server is /mcp add in the TUI, which writes to mcp.json for you.

File shape

{
  "$schema": "https://raw.githubusercontent.com/santhreal/veyyon/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "sqlite": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/sqlite-mcp-server/index.js"]
    }
  },
  "disabledServers": []
}

Top-level keys: mcpServers (map of name to config) and disabledServers (names to turn off). Server names match ^[a-zA-Z0-9_.-]{1,100}$. Shared per-server fields: enabled, timeout (milliseconds; 0 disables the client-side timeout), auth, and oauth. Stdio servers also take command, args, env, and cwd; remote servers take url plus type (or a type-less inferred URL) and headers.

Choose a transport

type is optional for stdio because it is inferred from command.

A minimal streamable HTTP server:

{
  "mcpServers": {
    "analytics": {
      "type": "http",
      "url": "https://analytics.example.com/mcp"
    }
  }
}

Pass environment variables

Local stdio servers often need environment variables:

{
  "mcpServers": {
    "sqlite": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/sqlite-mcp-server/index.js"],
      "env": { "DB_PATH": "/var/data/app.db", "SQLITE_LOG_LEVEL": "warn" }
    }
  }
}

A stdio server does not inherit the shell environment. It receives a baseline of variables a program needs in order to run — PATH, HOME, temp and locale settings, certificate and proxy settings, and the directories version managers use to resolve a command — plus whatever env sets. Every other ambient variable, including provider keys and CI tokens, is withheld. On Windows the baseline also carries PATHEXT, SystemRoot, ComSpec and the ProgramFiles variants, and names match without regard to case.

To forward an ambient variable, name it:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "envPassthrough": ["GITHUB_TOKEN"]
    }
  }
}

inheritEnv: true hands one server the whole environment, including every credential in it. Use it when a server needs a variable you cannot name in advance. It is set per server, and each spawn logs a warning stating the command.

{
  "mcpServers": {
    "legacy": { "command": "/opt/legacy/mcp", "inheritEnv": true }
  }
}

For HTTP servers, pass credentials or account ids as headers:

{
  "mcpServers": {
    "analytics": {
      "type": "http",
      "url": "https://analytics.example.com/mcp",
      "headers": { "Authorization": "Bearer ${ANALYTICS_MCP_TOKEN}", "X-Account-Id": "acct_123" }
    }
  }
}

Authenticate

Bearer token via header

Keep the token in the environment and reference it from a header rather than committing the raw value:

$ export ANALYTICS_MCP_TOKEN="your-token-value"

OAuth

Some HTTP servers require an interactive OAuth flow. Add an oauth block, then authenticate from the TUI with /mcp reauth <name>:

{
  "mcpServers": {
    "crm": {
      "type": "http",
      "url": "https://crm.example.com/mcp",
      "oauth": { "clientId": "veyyon-crm-client" }
    }
  }
}

Approve tools

Every tool an MCP server exposes appears namespaced as mcp__<server>__<tool> and is governed by the global tools.approvalMode plus per-tool tools.approval. To require a prompt for a specific server’s tools, set a per-tool policy:

# ~/.veyyon/profiles/default/agent/config.yml
tools:
  approval:
    mcp__sqlite__query: prompt

To turn a server off entirely, add its name to disabledServers in mcp.json.

In the TUI

Run /mcp list to see exactly which tools, resources, and templates Veyyon registered.

Resolve common errors

Server not found

For a stdio server, the command is usually not on PATH or the path is wrong. Check it directly:

$ node /path/to/sqlite-mcp-server/index.js

Fix the path, or add the directory to env.PATH. For an http server, check the URL with curl:

$ curl -i https://analytics.example.com/mcp

Timeout

If /mcp shows the server but tool calls time out, raise the per-server timeout (milliseconds), or set VEYYON_MCP_TIMEOUT_MS for the whole process:

{ "mcpServers": { "analytics": { "type": "http", "url": "…", "timeout": 60000 } } }

Authentication failure

For header tokens, confirm the environment variable is set in the same shell that starts Veyyon. For OAuth, run /mcp reauth <name> again. If a 401/403 persists, the token may have expired or the server may require additional headers.

Model cannot see the tools

If a server is connected but the model never uses its tools, check that the server is not in disabledServers, that enabled is not false, and that no tools.approval entry denies the namespaced tool. Run /mcp resources to see what was registered.

Where to go next

• MCP for the feature overview (MCP client; ACP is separate).
• Configuration for config file layout and precedence.
• Tools, skills, and extension data for other ways to extend Veyyon.