MCP Integration

MCP lets Anode use tools from local or remote servers. Anode supports stdio and basic HTTP JSON-RPC transports, tool filtering, OAuth tokens, and workspace trust.

Configure Servers

Define MCP servers in a JSON config file. Each server entry maps a name to a ServerConfig object.

Config Locations

Path	Scope	Loading
~/.config/anode/mcp.json	User	Always loaded
anode.json	Workspace	Requires trust, mcp.allowWorkspace: true, or ANODE_ENABLE_WORKSPACE_MCP=true; reads a top-level mcpServers object
.mcp.json	Workspace	Requires trust, mcp.allowWorkspace: true, or ANODE_ENABLE_WORKSPACE_MCP=true

User-level servers load first. Workspace servers merge in second.

ServerConfig Fields

Field	Type	Description
command	string	Executable to launch (stdio transport)
args	string[]	Arguments passed to command
env	map	Environment variables. Supports ${VAR} and ${VAR:-default} expansion
cwd	string	Working directory for the server process
url	string	HTTP endpoint (HTTP transport). Mutually exclusive with command
headers	map	HTTP headers sent with every request
includeTools	string[]	Tool name patterns to include. Only matching tools register
excludeTools	string[]	Tool name patterns to exclude. Matching tools are dropped

Set command for stdio servers. Set url for HTTP servers. Do not set both.

Stdio Server

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Anode spawns npx as a child process and communicates over stdin/stdout.

HTTP Server

{
  "mcpServers": {
    "remote-db": {
      "url": "https://mcp.example.com/v1",
      "headers": {
        "X-API-Key": "${MCP_DB_KEY}"
      },
      "includeTools": ["query_*"],
      "excludeTools": ["query_drop_table"]
    }
  }
}

The env expansion syntax works inside headers values too.

Trust Workspace Servers

Workspace-level MCP config files (anode.json and .mcp.json) do not load automatically. Anode requires explicit trust.

Trust a workspace:

anode mcp trust
anode mcp approve

This stores a SHA-256 hash of the workspace root path in ~/.config/anode/mcp-trust.json. The next time you open this workspace, Anode loads workspace MCP config without prompting.

Alternatively, set the environment variable to skip trust checks:

export ANODE_ENABLE_WORKSPACE_MCP=true

Or set the main config flag:

{
  "mcp": {
    "allowWorkspace": true
  }
}

When workspace MCP is enabled, Anode checks both anode.json and .mcp.json at the workspace root. In anode.json, MCP servers must be under a top-level mcpServers key, not under the main mcp settings object.

Manage User Servers

Add or remove user-level servers in ~/.config/anode/mcp.json:

anode mcp add docs --url https://example.com/mcp
anode mcp add local --env TOKEN=secret -- npx -y @modelcontextprotocol/server-filesystem .
anode mcp remove docs

--header KEY=VALUE adds HTTP headers for remote MCP servers configured with --url. --env KEY=VALUE and --cwd <dir> apply to stdio commands configured after --.

Tool Names

MCP tools register with a namespaced name:

mcp__<server>__<tool>

Both <server> and <tool> are sanitized: lowercased, restricted to alphanumeric characters, dashes, and underscores. For example, a tool readFile on server filesystem becomes mcp__filesystem__readfile.

Filter Tools

Use includeTools and excludeTools to control which tools a server exposes. Patterns are matched against tool names before registration.

• includeTools: Only tools matching at least one pattern are registered.
• excludeTools: Tools matching any pattern are dropped (applied after include).

Patterns support glob syntax. For example, ["read_*", "list_*"] matches read_file and list_dir.

MCP OAuth

Authenticate with remote MCP servers that require OAuth.

Login

anode mcp oauth login remote-db

This starts a browser-based OAuth PKCE flow:

1. Anode derives authorize and token URLs from the server URL (/oauth/authorize, /oauth/token).
2. A local callback server opens in your browser.
3. You approve access. Anode stores tokens in ~/.config/anode/mcp-oauth.json.

The Bearer token is automatically injected into HTTP headers for that server.

Flags

Flag	Description
--server-url <url>	MCP server URL (auto-detected from config if omitted)
--client-id <id>	OAuth client ID
--client-secret <secret>	OAuth client secret (if required)
--scopes <scopes>	OAuth scopes (space-separated)

When --server-url is omitted, Anode resolves the URL from the same MCP config set used by anode mcp: user config first, then trusted or explicitly enabled workspace config.

Token refresh

Anode refreshes tokens automatically with a 60-second buffer before expiry. No manual intervention needed.

Logout

anode mcp oauth logout remote-db

This clears stored credentials for the named server.

Status

anode mcp oauth status

Shows token status for all configured MCP servers - whether tokens are valid, expired, or absent.

CLI commands

List servers

anode mcp list

Shows configured server definitions without connecting to them. Use --connect to connect to servers and show connection status plus discovered tools. Use --timeout <duration> with --connect to override the connection timeout (default 10s). Explicit timeout values must be greater than zero.

Doctor

anode mcp doctor

Validates your MCP config files and tests connections to all servers. Use this to diagnose startup failures or misconfigured servers. Successful checks end with MCP doctor passed..

Connection status

anode mcp status

Shows the current connection state for configured MCP servers. Use this when a tool disappears from the registry or a server was expected to reconnect.

Server details

anode mcp info
anode mcp info filesystem

Prints one server or all servers with config details, discovered tools, and resources. Use it before changing include/exclude filters.

Tools and resources

anode mcp tools
anode mcp resources

tools lists every currently exposed MCP tool with its namespaced Anode name. resources lists resources exposed by connected servers.

Read one resource directly:

anode mcp read filesystem file:///home/user/project/README.md

Reload

anode mcp reload

Reconnects configured MCP servers in place. Use it after editing ~/.config/anode/mcp.json, anode.json, or .mcp.json instead of restarting the TUI.

Skill-local MCP

Skills can bundle their own mcp.json alongside SKILL.md. These servers activate lazily - only when the skill runs. See Agents and Skills for details on skill structure.

Enable skill-local MCP in config:

{
  "skills": {
    "allowMCP": true
  }
}

For compatibility, the workspace MCP environment gate also enables skill-local MCP when skills.allowMCP is not set:

export ANODE_ENABLE_WORKSPACE_MCP=true

The active profile and tool policy still apply to skill-local MCP tools.

Global MCP Settings

These keys live in your config.json under mcp:

Key	Type	Default	Description
allowWorkspace	bool	false	Allow workspace .mcp.json loading without explicit trust
connectTimeout	int	10	MCP connection timeout in seconds

{
  "mcp": {
    "allowWorkspace": false,
    "connectTimeout": 15
  }
}

Keep Going

• Toolbox - extend Anode with simple executables instead of MCP servers
• Agents and Skills - bundle MCP servers inside skills
• Configuration - full settings reference
• Permissions - control what MCP tools are allowed to do