Nous Portal MCP

Portable, read-only first adapter for selected Nous Portal capabilities.

Status: early review scaffold. It is not yet authenticated and cannot invoke paid tools.

The first slice exposes:

• nous_portal_status — local configuration status without credential output;
• nous_portal_routes — local derivation of the vendor-specific managed gateway origins with an explicit no-effect receipt.
• nous_portal_auth_start — request a device code without opening a browser;
• nous_portal_auth_poll — poll once and atomically persist approved OAuth state without returning token values.

It does not invoke paid tools, copy Hermes credentials, depend on Dione, or send private data. Merely installing the adapter does not start authentication.

The auth library stores each seat's OAuth state outside the plugin directory, uses mode 0600, and holds an exclusive lock across refresh-token exchange and atomic replacement. Nous refresh tokens are single-use; copying one into multiple seats or refreshing it without persisting the rotated token will invalidate the session.

Configuration

Each adopting seat supplies its own credentials:

NOUS_PORTAL_STATE_DIR=<required private local per-seat state directory>
NOUS_PORTAL_CLIENT_ID=<required Portal OAuth client ID>
NOUS_PORTAL_SPEND_LIMIT_USD=<future paid-call ceiling>
TOOL_GATEWAY_DOMAIN=nousresearch.com
TOOL_GATEWAY_SCHEME=https
FIRECRAWL_GATEWAY_URL=<optional vendor-specific override>

NOUS_PORTAL_STATE_DIR has no shared fallback. The adapter refuses auth configuration until the adopting seat supplies an explicit path. The path must be on a local filesystem owned by exactly one seat: POSIX advisory locks are not a safe coordination mechanism across NFS or other shared/network filesystems. Do not distribute access or refresh tokens through a shared .env.

Device login is deliberately two-step. nous_portal_auth_start returns the verification URL and user-facing code only to the adopting MCP client while keeping the private device code in the seat's mode-0600 state. It never opens a browser or sends the code to Discord. After the operator authorizes the request, nous_portal_auth_poll performs one poll; pending authorization returns a retry hint, and success atomically stores tokens without disclosing them in the tool result.

Hermes derives managed origins as <vendor>-gateway.<TOOL_GATEWAY_DOMAIN>, with an optional vendor-specific override. The current server reproduces that topology without making a network request. Until a private state directory is configured, status returns configuration_required; until that store contains OAuth state, it returns authentication_required.

Installation surfaces

The same dependency-free Python stdio server supports all clients. Packaging is deliberately separate from credentials: every adopting seat supplies its own OAuth state and spending authority.

Python / generic MCP

Install from a pinned Git commit:

python3 -m pip install \
  "nous-portal-mcp @ git+https://github.com/callisto-syn/nous-portal-mcp@<commit>"

The installed stdio command is:

nous-portal-mcp

See examples/generic-stdio.json.

Claude Code

Install the Python artifact in the construct's image or environment, then add the server entry from examples/claude-code.mcp.json. Each construct must use its own private state directory and receive its own adoption and spending clearance. Do not copy another seat's OAuth store: Nous refresh tokens rotate and are single-use.

For image-based deployments, examples/Dockerfile builds from the reviewed checkout supplied as its build context. Pin the checkout before building.

Codex

The repository is also a Codex plugin. Its .codex-plugin/plugin.json points to the repository-local .mcp.json, which launches the same server source.

Portability acceptance

Portability is not considered proven until a clean environment can:

1. install a pinned artifact;
2. start nous-portal-mcp over stdio;
3. complete an MCP initialize and tools/list handshake;
4. keep credentials and state outside the installed artifact;
5. uninstall without removing or exposing another seat's state.

Development

python3 -m unittest discover -s tests

The design and prior-art record lives in docs/step0.md.