NAME¶

nbox-serve - Run the MCP server for AI agents / MCP clients (read-only by default; `--allow-writes` enables the opt-in write tools)

SYNOPSIS¶

nbox serve [--http] [--http-token] [--oidc-issuer] [--audience] [--oidc-jwks-url] [--allowed-host] [--rate-limit] [--allow-writes] [--local-writes] [--print-config] [-h|--help]

DESCRIPTION¶

Run the MCP server for AI agents / MCP clients (read-only by default; `--allow-writes` enables the opt-in write tools).

Defaults to the stdio transport: an MCP host launches `nbox serve` as a subprocess and speaks JSON-RPC over its stdin/stdout. Passing `--http` switches to a loopback HTTP transport instead (requires the `http` build feature). Add `--oidc-issuer` + `--audience` to validate inbound IdP JWTs on `/mcp` and bind a routable interface.

OPTIONS¶

--http <ADDR>

Serve over HTTP on this address instead of stdio, e.g. `127.0.0.1:8080`. Loopback only unless `--oidc-issuer` is set; a routable bind requires the OIDC resource-server auth mode and a TLS terminator in front (reverse proxy)

--http-token <TOKEN>

Require `Authorization: Bearer <TOKEN>` on the HTTP `/mcp` endpoint. Only meaningful with `--http` (and only in loopback/no-OIDC mode). Also read from `NBOX_SERVE_TOKEN`

--oidc-issuer <URL>

OIDC issuer URL. Enables OAuth 2.1 resource-server mode: inbound IdP JWTs are validated on `/mcp` and Protected Resource Metadata is advertised. Requires `--audience`. Only meaningful with `--http`

--audience <VALUE>

Expected token audience — nbox's canonical resource URI. Required when `--oidc-issuer` is set; the IdP must mint this `aud` via the RFC 8707 `resource` parameter

--oidc-jwks-url <URL>

JWKS URL override. Default: discovered from the issuer's `/.well-known/openid-configuration` (then `oauth-authorization-server`)

--allowed-host <HOST>

Extra hostname to accept in the DNS-rebinding allow-list, on top of the `--audience` host and loopback. Repeatable. Only applies in OIDC/routable mode (a loopback bind stays loopback-only)

--rate-limit <N>

Per-caller request cap, in requests per minute, on the HTTP `/mcp` endpoint. Keyed on the caller (`sub`, else `client_id`, else peer IP). Over the limit → `429` with `Retry-After`. `0` (the default) disables it. Only meaningful with `--http`

--allow-writes

Enable MCP write tools (Pattern 2, DESIGN §24). Requires the `http` feature and `--http` (writes need the HTTP transport so the OIDC caller identity can be resolved to a per-user NetBox token via the `[serve.vault]` config). Without this flag (the default), all write tools reject with "writes disabled". Also read from `[serve].allow_writes`

--local-writes

Enable local single-user MCP writes over stdio. Uses the active profile token and the MCP host's tool approval; not valid for HTTP in this first cut. Also read from `[serve].local_writes`

--print-config

Print a copy-paste MCP server config (the `mcpServers` JSON object most hosts read) to stdout and exit, without starting the server or connecting to NetBox. The `command` is the absolute path to this binary; `args` echoes any `--profile`/`--config` you passed so the snippet reproduces your invocation. The token is left as a placeholder — set it via `nbox config init`, the `NBOX_TOKEN` env var, or the printed `env` block. For the HTTP/OIDC transport see docs/MCP.md (this prints the stdio recipe)

-h, --help

Print help (see a summary with '-h')