NovaOS MCP
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) or novaos_mcp_server_create (adds safe names, tenant guard, working health check).
  • The CLI's Dockerfile health check uses curl, which python:3.12-slim lacks, 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, optional secrets.env (read from a git-ignored .env next to the manifest at publish; refused if .env is 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:

  1. Read verb + joiner + write verb in either order (get_or_create, save_and_list) -> WRITE.
  2. read_write / write_read compounds -> WRITE.
  3. Whole-word read verb list|get|read|search|query|fetch|describe -> READ.
  4. 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.
  5. Anything else -> WRITE. (find, lookup, check, count are NOT read verbs.)
  • A manifest/service category database forces EVERY tool to write.
  • readOnlyHint: true alone 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 on tools/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

  1. novaos_mcp_name_check, novaos_manifest_validate {kind:"mcp"}.
  2. novaos-cli mcp publish --manifest manifest.json [--dry-run] (novaos_mcp_publish). Needs Docker + developer role.
  3. Platform admin: Approve, then Activate separately, then check Tool Health (Organization Console > Manage > MCP Servers / Build > Tools).
  4. 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 invoke only 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_deployed with a case that uses the tool).

Gateway facts

  • An agent's tools/list shows every published MCP tool in the org, not only declared dependencies.
  • MCPClient posts JSON-RPC to the base URL root and tracks Mcp-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).