Documentation

MCP

Connect external tool servers via Model Context Protocol — stdio or HTTP, with hot-add and deferred discovery.

Edit on GitHub

MCP lets you extend Nyzhi with external tool servers. Any tool server that speaks the Model Context Protocol can be plugged in — file systems, databases, APIs, SaaS integrations, or your own custom tools.

Nyzhi supports two transports: stdio and streamable HTTP.

Adding an MCP Server

Add a server to your config file:

Stdio transport — runs a local process:

# ~/.config/nyzhi/config.toml  (or <project>/.nyzhi/config.toml)

[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
env = { NODE_ENV = "production" }

HTTP transport — connects to a remote server:

[mcp.servers.my-api]
url = "https://mcp.example.com/sse"
headers = { Authorization = "Bearer sk-..." }

Via CLI

Add, list, and remove servers from the command line:

# Add a stdio server (project scope by default)
nyz mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .

# Add an HTTP server
nyz mcp add my-api --url https://mcp.example.com/sse

# Add to global config instead of project
nyz mcp add filesystem --scope global -- npx -y @modelcontextprotocol/server-filesystem .

# List all configured servers
nyz mcp list

# Remove a server
nyz mcp remove filesystem
nyz mcp remove my-api --scope global

Via .mcp.json

For compatibility with Claude and Codex, Nyzhi reads <project>/.mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "remote": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

Nyzhi maps command entries to stdio and url entries to HTTP. Invalid entries are logged as warnings and skipped.

How Connection Works

At startup, Nyzhi:

  1. Merges MCP servers from global config, project config, and .mcp.json
  2. Connects to each server via McpManager::start_all
  3. Calls tools/list on each connected server
  4. Registers every discovered tool into the local tool registry

Failing servers are logged and skipped — they won’t block startup.

Tool Naming

MCP tools appear in Nyzhi with a namespaced name:

mcp__<server_name>__<tool_name>

For example, a tool called read_file from a server named filesystem becomes mcp__filesystem__read_file.

Deferred Tool Discovery

When the total MCP tool count exceeds 15, Nyzhi switches to deferred mode:

  • Tools are registered but hidden from the initial tool list
  • A deferred index is saved to .nyzhi/context/tools/mcp-index.md
  • The agent discovers tools on demand using the tool_search tool

This keeps the initial prompt compact and reduces token usage.

Tip: For large MCP fleets (many servers with many tools), use targeted prompts so the agent searches for the right tools instead of loading everything.

Server Introspection

The MCP manager provides APIs for inspecting connected servers:

  • all_tools() — list every registered MCP tool
  • tool_summaries() — compact name + description list
  • server_info_list() — connection status for each server
  • connect_server() — hot-add a new server at runtime
  • stop_all() — disconnect all servers

Config Merge Behavior

MCP servers from project config extend (not replace) global servers:

# Global: ~/.config/nyzhi/config.toml
[mcp.servers.shared-db]
command = "my-db-mcp"

# Project: <project>/.nyzhi/config.toml
[mcp.servers.project-api]
url = "https://api.project.com/mcp"

Both shared-db and project-api are available at runtime.

# Filesystem access
[mcp.servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

# PostgreSQL
[mcp.servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { DATABASE_URL = "postgresql://localhost/mydb" }

# GitHub
[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_..." }

# Brave Search
[mcp.servers.brave-search]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-brave-search"]
env = { BRAVE_API_KEY = "..." }

Next Steps

  • Tools — the full built-in tool inventory
  • Configuration — MCP config reference
  • Hooks — automate workflows based on tool events
Back to overview