# nodus-mcp

`nodus-mcp` is the Research Workbench's thin stdio gateway to the bearer-authenticated
Streamable HTTP MCP server built into Nodus. It exposes only the architect-approved
tool allowlist and contains no graph logic or graph cache.

The stdio entry supports MCP `2026-07-28`'s stateless `server/discover` lifecycle and
legacy initialize-based clients. The upstream HTTP client probes for the same modern
lifecycle and falls back to legacy initialization when the installed Nodus build needs
it. Upstream-derived tool catalogs use a short private cache lifetime.

## Setup

```sh
npm install
npm run build
npm test
```

Set `NODUS_MCP_TOKEN` after enabling MCP in Nodus settings, or set
`NODUS_MCP_TOKEN_FILE` to a JSON file containing a `token` field. The upstream URL
defaults to `http://127.0.0.1:4319/mcp` and can be changed with `NODUS_MCP_URL`. Only plain-HTTP URLs using the exact loopback hostnames `127.0.0.1`, `localhost`, or `[::1]` and the exact `/mcp` path are accepted. Userinfo is rejected and redirects are never followed.

The gateway mirrors schemas from upstream `tools/list` at runtime for only the 30
contracted tools. It does not use Nodus's separate port-4321 Zotero bridge. When Nodus
MCP is disabled, `nodus_gateway_health` remains available and reports the exact enable
step; no empty graph result is fabricated.

`npm test` uses an in-process mock Streamable HTTP MCP server and covers a closed port,
bad bearer token, and allowlist drift.

License: MIT. See [LICENSE](LICENSE).