Field guide
MCP tool servers on NovaOS
Building, naming, publishing and activating MCP servers that agents call through the NovaOS MCP gateway; the read/write name classifier and -32042.
Authoring
- Scaffold:
novaos-cli mcp init --name <n> --lang python --publisher <slug>(FastMCP, streamable HTTP on :3000) ornovaos_mcp_server_create(adds safe names, tenant guard, working health check). - The CLI's Dockerfile health check uses
curl, whichpython:3.12-slimlacks, and runs as root: fix both (the server's template does). - Manifest (MCP v2.0):
name,version(X.Y.Z),publisher,categories,tools[{name, description, capability: read|write|read_write, parameters}],health_check, optionalsecrets.env(read from a git-ignored.envnext to the manifest at publish; refused if.envis tracked by git). - Agents call tools as
<publisher>.<server>.<tool>(e.g.orbitron-fde.assetnova-mcp.db_search).
The read/write name classifier (critical)
NovaOS classifies each tool by the LEAF of its name and fails closed:
- Read verb + joiner + write verb in either order (
get_or_create,save_and_list) -> WRITE. read_write/write_readcompounds -> WRITE.- Whole-word read verb
list|get|read|search|query|fetch|describe-> READ. - Whole-word write verb
create|update|delete|write|put|post|patch|insert|upsert|remove|set|send|execute|invoke|mutate|replace|destroy|drop|alter|grant|revoke|store|save-> WRITE. - Anything else -> WRITE. (
find,lookup,check,countare NOT read verbs.)
- A manifest/service category
databaseforces EVERY tool to write. readOnlyHint: truealone does not avoid confirmation.
Consequence: in USER-scoped runs, write-classified tools get JSON-RPC -32042 (HITL_REQUIRED / WRITE_CONFIRMATION_REQUIRED), even inside HTTP 200. Service-account runs can call them only with an exact SA tool grant (admin console). The agent setting "Auto-confirm write operations" does not lift policy-required decisions.
Fix: read-named read-only tools that really refuse writes server-side; real writes go back to the backend (returned writes) or run as a service account. Tool: novaos_mcp_name_check.
Tenancy and auth inside your MCP server
- The gateway keeps one downstream session per tenant; read tenant and env per HTTP request. The tenant header (
X-Tenant-ID) arrives ontools/call, not at session init. Never take the tenant from model arguments. - Never forward the execution token to your backend. Mint your own org-scoped client_credentials token (
resource=urn:<app>,scope=<app>:agent-tools,organization_id), from an M2M app added to EACH org with a machine-to-machine role. The backend issuer must equal the MCP's Logto endpoint, else every callback 401s. - Only "safe" custom headers are forwarded by the gateway.
Publishing and activation
novaos_mcp_name_check,novaos_manifest_validate {kind:"mcp"}.novaos-cli mcp publish --manifest manifest.json [--dry-run](novaos_mcp_publish). Needs Docker + developer role.- Platform admin: Approve, then Activate separately, then check Tool Health (Organization Console > Manage > MCP Servers / Build > Tools).
- Release order: backend first, then MCP (publish + approve + activate), then agents that use it. An agent pinning a newer MCP must not publish before it.
- Externally deployed server:
novaos-cli mcp register --manifest --url. - Logs:
novaos-cli mcp logs <server-id>/mcp pod-logs <service-id>. novaos-cli mcp invokeonly talks to a local sandbox gateway (no token), so it does not test real behavior. Test MCP tools through a published agent that calls them (novaos_test_deployedwith a case that uses the tool).
Gateway facts
- An agent's
tools/listshows every published MCP tool in the org, not only declared dependencies. MCPClientposts JSON-RPC to the base URL root and tracksMcp-Session-Id; a 400/401/404 on a reused session means the gateway forgot it: reset and resend once (reads/idempotent only).- Error shapes to handle: JSON-RPC
error,result.isError, and an error inside a successful result.-32601= tool/method unavailable (wrong name, not published/active, too old).