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.

   Write it in four parts, in this order:

   1. What the server does — one sentence.
   2. When to use it — the concrete scenarios, not a restatement of the summary.
   3. Workflow — the order the tools are meant to be called in, numbered.
   4. ABSOLUTE RULE — that operations covered by this server must not be done through filesystem, terminal, code_exec or direct file access.

   MyServer provides X and Y tools.
   
   Use it when the task involves:
   - doing something only this server handles;
   - ...
   
   Workflow:
   1. tool_a — step one.
   2. tool_b — step two.
   
   ABSOLUTE RULE — NEVER bypass MCP tools:
   You MUST NOT use filesystem, terminal, code_exec, or any direct file access for operations covered by this server. Use only the MCP tools listed above.

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. Smoke-test startup and read the exit code — it is the whole signal:

   cd mcp-servers/<name> && timeout 5 .venv/bin/python -m app.mcp_server; echo "EXIT_CODE=$?"

   | Exit code | Meaning | |---|---| | 124 | timeout killed a server that was still running. Success. | | 0 | The server exited on its own before 5 seconds. Failure — usually main() is missing its parentheses at the bottom of the file. | | anything else | Traceback or crash. Read it and fix. |

   Never run the server without timeout: an MCP server blocks forever and the terminal hangs. Repeat until you get 124, then move on to registration.

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

reload_tools comes first, always. A newly written config is not read and a newly registered server is not connected until reload_tools runs: it re-reads mcp_servers.d/, reconnects every server, and registers their tools. Calling test_mcp_tool before it fails with "not connected" every time and burns an iteration. The auto-registration some tools do when they write the config does not connect anything.

reload_tools is likewise what ends every later edit — to the server code or to its config — since nothing else picks those up. It is not needed for tool arguments, nor for data files the server reads per call. The server's own INSTRUCTIONS, though, is read at connect time and merged into the system prompt, so editing it does need the reconnect.

6.1 Check connection

Call mcp_status. You should see your server as connected with the correct tool count. This step is discovery only — it tells you the server is up, never that a tool works.

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 — which means back to reload_tools before the next test.

If test_mcp_tool answers "MCP server '' is not connected", work the list in order rather than retrying blindly:

1. mcp_status — is the server listed, and as connected or disconnected?
2. Read mcp_servers.d/<name>.json and check that command and cwd are absolute paths that exist.
3. reload_tools.
4. test_mcp_tool again.
5. Still failing — the code is at fault: back to syntax check and the timeout smoke test, then repeat from here.

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

6.4 Code review before connecting

Before the first reload_tools, run a review pass over the file with filesystem action query — it reads the file for you and answers, instead of pulling the whole thing into context:

filesystem(action="query", path="mcp-servers/<name>/app/mcp_server.py",
  question="Check these 4 critical patterns: 1) main() is called with parentheses at the very end, 2) all @mcp.tool decorators appear before main(), 3) every parameter uses Annotated[..., Field(description=...)], 4) INSTRUCTIONS is not empty.")

Those four are what the timeout smoke test and mcp_status cannot see: a server whose tools are defined after mcp.run() starts fine, stays connected, and silently exposes nothing.

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

10b. Delegating the implementation

A sub-agent is a good fit for "write this server" when the tool set is large, the logic is involved, or an external API is in play — the write-debug loop would otherwise run 10+ tool calls in the main context. Give it, in the briefing:

• the exact server directory and file to edit;
• every tool name with its parameters, description and expected return format;
• how to verify: python -m py_compile, then the timeout smoke test with exit code 124 as the pass condition.

The sub-agent cannot register, connect or test the server: reload_tools, test_mcp_tool and mcp_status are the main agent's. It also does not inherit the main agent's memory or conversation — write the briefing into the context_transfer scratchpad section before spawning, since that is injected automatically. Registration, connection, per-tool testing and the report stay inline.

11. Workflow checklist for Navi

When asked to create a new MCP server:

1. Read this manual (manuals/create_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 — tools and a full INSTRUCTIONS (§3.2; it is read at connect time, so it must be there before step 9).
5. Code review: filesystem action query for the four critical patterns (§6.4).
6. Validate syntax: code_exec or terminal with python -m py_compile ....
7. Smoke-test startup under timeout until the exit code is 124 (§4.2).
8. Edit mcp_servers.d/<name>.json via filesystem to register the server.
9. Call reload_tools — mandatory before any test_mcp_tool.
10. Call mcp_status to confirm the server is connected.
11. Call test_mcp_tool for every tool.
12. Report results to the user.