Writing MCP Servers for Navi

This manual describes how to create, test, register, and maintain MCP servers that extend Navi's capabilities. Read this before you start building a new server.

1. Philosophy: Why MCP instead of user tools?

MCP servers run in isolated processes and communicate via the Model Context Protocol. They cannot crash Navi's core, they can be reloaded without restarting the server, and they scale to complex external integrations (APIs, databases, browsers, etc.). The trade-off is slightly more boilerplate than a single tools/foo.py file.

Rule: Every new capability that is not trivial (more than a simple datetime or notes lookup) should be built as an MCP server.

2. Directory structure

MCP servers live under:

mcp-servers/<server_name>/
├── pyproject.toml
├── README.md
└── app/
    ├── __init__.py
    └── mcp_server.py

• <server_name> — snake_case or kebab-case. Must match the key you will use in mcp_servers.d/<name>.json.
• pyproject.toml — Python package metadata and dependencies.
• app/mcp_server.py — the actual server code (FastMCP).

3. Creating a new server from the template

Use the built-in tool create_mcp_server (preferred) or copy the template manually:

cp -r mcp-servers/_template mcp-servers/my_server
cd mcp-servers/my_server
# Edit pyproject.toml: change name, description, add dependencies
# Edit app/mcp_server.py: add your tools and instructions

3.1 pyproject.toml

Minimal required fields:

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mcp-server-myserver"
version = "0.1.0"
description = "What this server does"
requires-python = ">=3.11"
dependencies = [
    "mcp>=1.27",
    "pydantic>=2.0",
    # add your own: httpx, asyncpg, playwright, etc.
]

[project.scripts]
mcp-server-myserver = "app.mcp_server:main"

[tool.setuptools.packages.find]
where = ["."]
include = ["app*"]

3.2 app/mcp_server.py

Read the template at mcp-servers/_template/app/mcp_server.py first. It contains a working hello-world server with extensive inline comments.

Key sections you must edit:

1. INSTRUCTIONS — These are injected into Navi's system prompt. Describe:

   • What this server does and when to use it.
   • Recommended workflow (order of tool calls).
   • ABSOLUTE RULE about never bypassing these tools with filesystem/terminal.

2. mcp = FastMCP("name", instructions=INSTRUCTIONS) — The name should match the directory key.

3. Tool functions — Each tool:

   • Is an async def.
   • Uses @mcp.tool(name="tool_name").
   • Parameters use Annotated[T, Field(description="...")] — never plain types.
   • Returns a plain str (JSON string for structured data is fine).
   • Raises on real errors.
   • Validates required params explicitly.

Example:

@mcp.tool(name="search_docs")
async def search_docs_tool(
    query: Annotated[str, Field(description="Search query string.")],
    limit: Annotated[int, Field(description="Max results.")] = 10,
) -> str:
    """Search the documentation index."""
    if not query.strip():
        raise ValueError("query is required and cannot be empty.")
    results = await _do_search(query, limit)
    return json.dumps(results, ensure_ascii=False, indent=2)

4. Environment and installation

After creating files, you must:

1. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate
   pip install -e .

2. Verify the server starts without crashing:

   timeout 5 python -m app.mcp_server || true

   If it prints a traceback, fix the code before proceeding.

5. Registering the server in Navi

Create a file mcp_servers.d/<name>.json in the project root. The filename (without .json) becomes the server name. Example for a server named my_server:

{
  "transport": "stdio",
  "command": "/absolute/path/to/mcp-servers/my_server/.venv/bin/python",
  "args": ["-m", "app.mcp_server"],
  "cwd": "/absolute/path/to/mcp-servers/my_server",
  "env": {
    "MCP_TRANSPORT": "stdio"
  },
  "groups": {
    "default": ["search_docs", "read_doc"]
  },
  "instructions": "Optional extra instructions merged with the server's own INSTRUCTIONS."
}

Critical fields:

• command — absolute path to the venv's Python binary.
• cwd — absolute path to the server directory.
• The filename must be <name>.json (e.g. my_server.json).
• args — usually ["-m", "app.mcp_server"].
• groups — organize tools into named groups so profiles can reference them cleanly.

After editing mcp_servers.d/<name>.json, call reload_tools to connect the server and register its tools.

6. Testing

6.1 Check connection

Call mcp_status. You should see your server as connected with the correct tool count.

6.2 Test each tool

Call test_mcp_tool for every tool your server exposes:

test_mcp_tool(server_name="my_server", tool_name="search_docs", arguments={"query": "hello", "limit": 3})

If any tool fails, read the error output, fix the code in app/mcp_server.py, and repeat.

6.3 Manual stderr inspection

If mcp_status shows disconnected but the code looks correct, inspect stderr manually:

cd mcp-servers/my_server
.venv/bin/python -m app.mcp_server 2>&1 | head -n 20

7. Updating an MCP server

1. Edit the code in mcp-servers/<name>/app/mcp_server.py.
2. (Optional) If you added new dependencies, edit pyproject.toml and run pip install -e . inside the venv.
3. Call reload_tools to reconnect the server and re-register tools.
4. Call test_mcp_tool to verify.

8. Deleting an MCP server

1. Remove the server directory or move it to a backup location.
2. Remove the entry from mcp_servers.d/<name>.json.
3. Call reload_tools.

9. Connecting an external MCP server

If the server was written by someone else:

1. Clone or place the server code on disk.
2. Create its venv and install dependencies.
3. Read its README to learn tool names and required environment variables.
4. Add an entry to mcp_servers.d/<name>.json with the correct command, cwd, args, and env.
5. Define groups mapping the tools into logical sets.
6. Call reload_tools.
7. Call test_mcp_tool for a representative tool.

10. Common mistakes and debugging

11. Workflow checklist for Navi

When asked to create a new MCP server:

1. Read this manual (manuals/write_mcp_server.md).
2. Read the template (mcp-servers/_template/app/mcp_server.py).
3. Call create_mcp_server(name=..., description=...) to scaffold the directory.
4. Edit app/mcp_server.py iteratively using filesystem.
5. Validate syntax: code_exec or terminal with python -m py_compile ....
6. Test startup: terminal with timeout 5 python -m app.mcp_server.
7. Edit mcp_servers.d/<name>.json via filesystem to register the server.
8. Call reload_tools.
9. Call test_mcp_tool for every tool.
10. Write good INSTRUCTIONS inside mcp_server.py.
11. Report results to the user.