MCP

nod is an MCP client. Servers you configure are available to the interactive shell, nod ask, ACP sessions, and authorized subagents.

For transports, protocol revisions, schema handling, and isolation guarantees, see the MCP protocol reference.

Add a remote server

/mcp add --transport http adds or replaces a remote Streamable HTTP server, saves it to ~/.nod/mcp.json, and reloads MCP:

/mcp add --transport http prisma https://mcp.prisma.io/mcp

To configure headers, authentication, required startup, or other options, edit the saved entry in mcp.json. Use "type": "http" for Streamable HTTP. Use "type": "sse" only for a deprecated 2024-11-05 HTTP+SSE server. Both require a url.

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

After editing an entry by hand, apply the change without restarting nod:

/mcp reload

Add a local stdio server

/mcp add adds or replaces a local stdio server:

/mcp add local-tools npx -y @modelcontextprotocol/server-everything

To configure one by hand, use "type": "local" or "type": "stdio". The canonical command form is an array whose first item is the executable:

{
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": ["node", "/absolute/path/to/server.js", "--read-only"],
      "environment": {
        "LOG_LEVEL": "warn"
      }
    }
  }
}

This compatibility form is also accepted:

{
  "mcp": {
    "filesystem": {
      "command": "node",
      "args": ["/absolute/path/to/server.js", "--read-only"],
      "env": {
        "LOG_LEVEL": "warn"
      }
    }
  }
}

environment is canonical; env is an alias. Every value must be a string. Local servers inherit the nod process environment, then configured values override matching inherited variables. They communicate with nod using newline-delimited JSON-RPC over stdin and stdout.

For an exact docker run stdio command without --cidfile, nod injects a private container ID file and removes the owned container after shutdown or startup failure. If you supply --cidfile, cleanup remains your responsibility.

Authenticate a remote server

Choose the narrowest mechanism the server accepts:

A literal Authorization header is rejected so credentials do not become ordinary profile data.

{
  "mcp": {
    "protected": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "header_env": {
        "X-Workspace": "MCP_WORKSPACE"
      },
      "oauth": {
        "client_metadata_url": "https://example.com/nod-client.json",
        "scopes": ["tools.read", "tools.call"]
      }
    }
  }
}

Start or clear an OAuth session from the shell:

/mcp auth <name> --open

/mcp logout <name>

In an interactive session, nod discovers protected-resource and authorization-server metadata, validates the issuer, refreshes tokens, and answers scope challenges. It uses a Client ID Metadata Document when one is configured and advertised, and falls back to Dynamic Client Registration. Every oauth field is optional: resource, issuer, client_id, client_secret_env, client_metadata_url, and scopes.

Malformed credential entries are isolated so valid servers still work, then removed on the next successful authentication or logout. Callback issuer mismatches fail authentication instead of suggesting an unsafe override.

OAuth credentials are stored in a private 0600 file under ~/.nod/. ACP is noninteractive, so an ACP host must supply headers for a protected MCP server.

Manage servers

Run /mcp to browse server health, tools, resources, templates, and prompts. You can inspect schemas and preview resource or prompt content. Content enters the composer only after you choose Insert. The browser also supports add, remove, reload, authentication, logout, and project trust.

Direct slash commands remain available:

/mcp list
/mcp resource list <server>
/mcp resource templates <server>
/mcp resource read <server> <uri>
/mcp resource complete <server> <uri-template> <variable> [value]
/mcp prompt list <server>
/mcp prompt get <server> <name> [arguments-json]
/mcp prompt complete <server> <name> <argument> [value]
/mcp add <name> <command> [args...]
/mcp add --transport http <name> <url>
/mcp remove <name>
/mcp reload
/mcp auth <name> --open
/mcp logout <name>
/mcp trust approve <name>
/mcp trust reject <name>
/mcp trust approve-all
/mcp trust reset
/mcp path

/mcp list

While discovery is running, the status view reports it as in progress. Afterward it shows a health snapshot for each server, never including commands, environment values, headers, credentials, raw responses, or server URLs.

/mcp reload builds and connects the new configuration before it replaces the running one. If the file is invalid or a required server fails, nod keeps the servers you already had. If an optional server fails, the reload still goes through without it. A valid but empty profile removes every server.

Every operation is also available outside the shell as a top-level nod mcp command; see MCP management in the CLI reference. nod status and nod doctor report profile warnings and project configuration issues without starting MCP transports or opening credential storage; their JSON output marks the connection check as not_checked.

Servers with setup guides

Any server that documents a generic MCP client works with nod: use its stdio command with /mcp add, or its Streamable HTTP URL with /mcp add --transport http, and follow its authentication instructions with the headers, header_env, bearer_token_env, or oauth fields above. Guides written for other MCP clients apply unchanged; only the config file location differs.

Profile configuration

Your private MCP profile lives at ~/.nod/mcp.json. /mcp path prints the exact profile path:

/mcp path

The canonical root object contains one mcp map. mcpServers is accepted as a compatibility alias, but mcp wins when both exist and nod always writes mcp. Similar unsupported keys such as MCP-Servers produce a warning and block profile mutations so nod cannot overwrite an ambiguous file.

Names passed to MCP commands must contain only letters, numbers, _, or -. Use the same form for names you add by hand, so generated tool names stay predictable.

{
  "mcp": {
    "local-tools": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true,
      "required": false,
      "environment": {
        "TOKEN": "value"
      }
    },
    "remote-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "enabled": true
    }
  }
}

Common server fields apply to both local and remote profile entries:

All timeout values are positive integers. restart_limit applies only to stdio servers.

Project configuration and trust

A workspace can provide Claude-compatible MCP configuration at <workspace>/.mcp.json. nod opens it as a bounded no-follow regular file and reads only the top-level mcpServers object:

{
  "mcpServers": {
    "project-local": {
      "command": "npx",
      "args": ["-y", "@example/project-server", "${PROJECT_ROOT:-.}"],
      "env": {
        "PROJECT_TOKEN": "${PROJECT_TOKEN}"
      }
    },
    "project-remote": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "X-Workspace": "${WORKSPACE_ID}"
      }
    }
  }
}

Project servers begin as pending and stay disconnected on every surface. Interactive nod presents a trust prompt after startup. Approve or reject individual entries, approve the complete file, or clear the workspace choices:

/mcp trust approve <name>
/mcp trust reject <name>
/mcp trust approve-all
/mcp trust reset

The same actions are available as nod mcp trust ... commands. Trust is saved in your private ~/.nod/settings.json under the canonical workspace path, never in .mcp.json. Before approval, nod does not start a project process, contact a project endpoint, read an environment value, or load stored MCP credentials. nod ask reports skipped pending servers on stderr, and ACP leaves them unavailable.

After approval, ${VAR} and ${VAR:-default} expand in project commands, arguments, environment values, and HTTP headers. Missing required variables skip only the affected server and appear as configuration issues without exposing values. The file is limited to 1 MiB, and expanded values use a separate 1 MiB aggregate budget. Project servers are always optional even if they contain "required": true.

Template expansion is project-only. Profile strings remain literal; use environment, header_env, or bearer_token_env when a profile entry needs process environment values.

In native interactive and nod ask sessions, a profile entry wins a same-name project entry. ACP request entries win same-name project entries and do not inherit profile servers.

How tools reach the model

Tools are discovered when needed. capability_search searches installed skills and configured MCP tools using a query, optionally restricted to one exact server alias. Matching tool schemas load automatically within the schema budget. The agent can also use mcp_select_tool to select a tool explicitly.

Selected tools are namespaced as mcp_<server>_<tool> and sanitized to avoid collisions with built-ins. Server instructions, descriptions, search results, and selected schemas are bounded by context limits.

Dynamic MCP tool calls use the same permission policy as built-in tools, re-checked immediately before transport.

Treat server config as sensitive

MCP environment values can contain credentials, and server tools execute with the authority their process or endpoint provides. Keep ~/.nod/mcp.json private, review project .mcp.json before approving it, never commit literal secrets, and use narrowly scoped tokens.

Server output is untrusted input, not instructions. See Trust and security for what nod enforces, and Troubleshooting when a configured server does not appear.

Browse all nod documentation

View this page as Markdown · llms.txt