Nexidion MCP 1.2.0

MCP server that exposes the Nexidion knowledge base as tools. Wraps the REST API — no raw SQL — so Nexidion's own auth and per-vault permissions still apply.

It runs in two modes, with two different identity models:

delete_node is deliberately not reachable from the public connector: it is irreversible, and it is still one Claude Code session away.

Files

• server.py — the tools, plus both transports.

• oauth.py — OAuth authorization server for the HTTP mode (state in SQLite).

• Dockerfile, requirements.txt — the image the Pi runs.

• .env — stdio config: NEXIDION_BASE_URL, NEXIDION_USER, NEXIDION_PASSWORD (chmod 600, git-ignored).

Related MCP server: obsidian-brain

stdio (Claude Code) — already registered, user scope

claude mcp add --scope user nexidion -- \
  /home/rhab/projects/nexidion-mcp/.venv/bin/python \
  /home/rhab/projects/nexidion-mcp/server.py

Verify: claude mcp list / claude mcp get nexidion. In a session: /mcp. MCP tools load at session start — use a NEW session.

Self-test against an explicitly configured API: .venv/bin/python server.py --selftest. The login token is immediately exchanged at /api/auth/actor-token; all subsequent requests carry actor_type=mcp, so stdio cannot bypass AI visibility or write policy.

HTTP (claude.ai custom connector)

Add it in claude.ai under Settings → Connectors → Add custom connector, URL:

https://mcp.nexidion.org/mcp

Claude then registers itself (RFC 7591 dynamic client registration), redirects you to a login page served by this server, and you sign in with your own Nexidion username and password. Every tool call afterwards runs as that user.

How the auth actually works

claude.ai will only talk to a remote MCP server over OAuth, so this server is an OAuth authorization server — the MCP SDK supplies the /authorize, /token and /register handlers, oauth.py supplies the storage, and /login supplies the one thing OAuth can't know: who the human is. That is answered by posting the credentials to Nexidion's existing /api/auth/login.

The catch: Nexidion's own JWTs expire after 8 hours, and we never store your password, so we cannot re-login for you later. Instead the container is given the app's JWT_SECRET_KEY and mints a short-lived (5 min) Nexidion JWT per request for the user bound to the access token. That is why the connector stays connected indefinitely, and why this container is as security-critical as the app itself: holding that key, it could forge a token for any user. It only ever does so after that user has proved their password.

Tokens: access 1 h, refresh 90 days and rotated on every use. Only SHA-256 hashes are stored. whoami reports which Nexidion user Claude is currently acting as.

Every short-lived Nexidion JWT used for an HTTP or stdio tool call includes the trusted actor_type=mcp claim. Nexidion therefore retains the user identity for vault permissions and auditing while applying inherited node AI-access policies to the request. Relevant read tools default to include_quarantined=false; explicit opt-in never bypasses an AI-invisible policy.

Tests

Install the pinned runtime and test dependencies in a clean environment, then run:

python -m pip install -r requirements-dev.txt
python -m pytest -q

The committed tests cover stdio actor-token exchange, HTTP MCP claims, and policy option forwarding. local_smoke_test.py exercises initialization and authentication against an explicitly selected local Nexidion instance.

Config (set by compose on the Pi, not by .env)

Deploy

Cross-build on WSL, push to Hub, pin by digest — same rule as the app, so there is always a digest to roll back to:

docker buildx build --builder nxbuilder --platform linux/arm64 \
  -f Dockerfile -t rhabermann/nexidion-mcp:vN --push .
docker buildx imagetools inspect rhabermann/nexidion-mcp:vN --format '{{.Manifest.Digest}}'
# then on the Pi: put that digest in ~/nexidion/docker-compose.yml
ssh rhab@192.168.178.63 'cd ~/nexidion && docker compose pull mcp && docker compose up -d --no-deps mcp'

Wiping nexidion_mcp-state forces every connector to re-authorize — that is the kill switch if a token ever leaks:

docker compose rm -sf mcp && docker volume rm nexidion_mcp-state && docker compose up -d --no-deps mcp

Tools

Reads: whoami, list_vaults, get_vault, list_nodes, get_node, search (full-text), find_node_by_title, get_node_versions, get_version, bulk_get_nodes, list_tasks, get_task. Writes: create_node, update_node, move_node, set_summary, create_task (queues the Nexidion AI agent). delete_node (destructive) — stdio only.

Permissions (~/.claude/settings.json)

Reads + non-destructive writes + create_task are allowlisted (mcp__nexidion__*). delete_node is in ask → always prompts.

Admin

• stdio base URL points at the Pi over the LAN (http://192.168.178.63:5001). For off-LAN use, switch NEXIDION_BASE_URL to https://caddy.nexidion.org in .env.

• The stdio account has only the vault access assigned in Nexidion. Revoke access through the Admin UI rather than relying on a hard-coded user ID.

• To rotate the stdio password, reset the configured account and update .env.

• Rotating JWT_SECRET_KEY logs everyone out of the app and invalidates the connector's minted JWTs — restart both containers together.