NV oOS MCP Bridge

io.github.nvdigitalsolutionsv0.1.0-alpha.4Updated Oct 8, 2026

Stdio relay connecting Zed, Claude Desktop, Cursor and Codex to NV oOS WordPress MCP endpoints.

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper Tools

Overview

AI-generated overview

A local stdio relay that connects desktop AI clients to an NV oOS WordPress site's MCP endpoint over HTTPS or an SSH tunnel.

What it does
This package bridges stdio-based MCP clients to a remote NV oOS (Open Operator System) WordPress JSON-RPC 2.0 MCP endpoint. It reads one JSON-RPC object per stdin line, POSTs it to the configured endpoint with a Bearer token, and writes the response back on stdout. A second binary, nvoos-mcp-ssh, manages an ssh -N -L port-forward for sites that are only reachable over SSH, tearing the tunnel down when the relay exits.
When to use it
Use it when a desktop MCP client such as Zed, Claude Desktop, Cursor, Codex, or VS Code needs to talk to an NV oOS WordPress site's MCP endpoint, especially when the site is HTTPS-reachable or locked down to SSH-only access.
Requirements
Node.js with npx to run the npm package locally. Requires MCP_AI_BASE_URL (full MCP endpoint URL) and a token in MCP_AI_TOKEN, minted in the site's Fleet Operator admin screen. The SSH variant additionally needs MCP_AI_SSH_USER and MCP_AI_SSH_HOST, plus working non-interactive key-based SSH. Optional variables cover timeout, Host header, and an env file.
Before you install
MCP_AI_TOKEN is a secret credential or operator token; keep it out of settings files and process arguments, using the env file instead. The relay sends requests to the configured WordPress site, so the token grants whatever scope it was minted with. The SSH variant opens a port-forward to the remote host and relies on key-only SSH access.

Installation

In SourceWeft

  1. Open NV oOS MCP Bridge in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@nvdigitalsolutions/nvoos-mcp-bridge

Zero-dependency MCP stdio ↔ HTTP relay for NV oOS (Open Operator System) WordPress sites.

Every NV oOS site exposes a JSON-RPC 2.0 MCP endpoint at https://<site>/wp-json/mcp-ai/v1/mcp. Most editors and agents (Zed, Claude Desktop, Cursor, Codex) spawn MCP servers over stdio — this package bridges the two transports. Two binaries ship:

BinaryUse when
nvoos-mcpThe site is reachable over HTTPS (normal case)
nvoos-mcp-sshThe site is SSH-only (locked-down VPS / Cloudways droplet) — owns the ssh -N -L port-forward for you
bash
npx -y @nvdigitalsolutions/nvoos-mcp-bridge@latest

Quick start (Zed)

zed: open settings → add to context_servers:

jsonc
"nv-oos": {  "source": "custom",  "command": {    "path": "npx",    "args": ["-y", "@nvdigitalsolutions/nvoos-mcp-bridge@latest"],    "env": {      "MCP_AI_BASE_URL": "https://your-site.com/wp-json/mcp-ai/v1/mcp",      "MCP_AI_TOKEN":    "cred_xxxxx.SECRET"    }  }}

Then reload the Agent Panel (agent: restart language servers → or reopen the panel). Use the Fleet Operator admin screen (Settings → External Operators) to mint a scoped operator token and get a ready-pasted block.

SSH-only sites

jsonc
"nv-oos-ssh": {  "source": "custom",  "command": {    "path": "npx",    "args": ["-y", "@nvdigitalsolutions/nvoos-mcp-bridge@latest", "ssh"],    "env": {      "MCP_AI_SSH_USER": "your-ssh-user",      "MCP_AI_SSH_HOST": "203.0.113.10",      "MCP_AI_SSH_PORT": "22",      "MCP_AI_TOKEN":    "op_xxxxx.SECRET"    }  }}

Pass ssh as the first argument to select the SSH binary via npx (npx exposes only the primary bin as the bare package name). SSH auth is key-only: ssh <user>@<host> must work non-interactively first.

Other clients

Same env vars, different shells — Claude Desktop (claude_desktop_config.json → mcpServers), Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json):

json
{  "mcpServers": {    "nv-oos": {      "command": "npx",      "args": ["-y", "@nvdigitalsolutions/nvoos-mcp-bridge@latest"],      "env": {        "MCP_AI_BASE_URL": "https://your-site.com/wp-json/mcp-ai/v1/mcp",        "MCP_AI_TOKEN": "cred_xxxxx.SECRET"      }    }  }}

On Windows hosts, some clients need the cmd wrapper: "command": "cmd", "args": ["/c", "npx", "-y", "@nvdigitalsolutions/nvoos-mcp-bridge@latest"].

Configuration

All configuration is environment variables — never put tokens in args (they would show in process listings).

nvoos-mcp (HTTPS relay)

VariableRequiredDefaultPurpose
MCP_AI_BASE_URL✅—Full URL of the MCP endpoint, e.g. https://example.com/wp-json/mcp-ai/v1/mcp
MCP_AI_TOKEN⚠️—Bearer credential (cred_xxxxx.SECRET or operator op_xxxxx.SECRET); unauthenticated if unset
MCP_AI_HOST_HEADER—Override the HTTP Host header (sites that canonical-redirect on Host behind proxies/tunnels)
MCP_AI_HTTP_TIMEOUT120000Request timeout in ms
MCP_AI_ENV_FILE~/.nvoos-bridge.envEnv file for secrets (see below)

nvoos-mcp-ssh (SSH variant)

Adds MCP_AI_SSH_USER, MCP_AI_SSH_HOST (both required), MCP_AI_SSH_PORT (default 22), MCP_AI_SSH_REMOTE_HOST (default localhost), MCP_AI_SSH_REMOTE_PORT (default 80), MCP_AI_LOCAL_PORT (default: free port), MCP_AI_SSH_CMD (default ssh), MCP_AI_SSH_EXTRA_ARGS, MCP_AI_SSH_BATCH_MODE, MCP_AI_SSH_READY_MS (default 15000). Same token, Host-header, timeout, and env-file variables as the HTTPS relay.

Secret file

Keep tokens out of settings files:

bash
# ~/.nvoos-bridge.env  (chmod 600)MCP_AI_BASE_URL=https://your-site.com/wp-json/mcp-ai/v1/mcpMCP_AI_TOKEN=cred_xxxxx.SECRET

Values already present in the process environment win over the file, so per-project overrides still work.

Behavior contract

  • Reads one JSON-RPC 2.0 object per stdin line, POSTs it to the endpoint (Authorization: Bearer …), writes the response as one stdout line.
  • Notifications (no id) get no response, ever.
  • All diagnostics go to stderr — stdout carries MCP messages only.
  • On stdin EOF, in-flight requests drain before exit.
  • The SSH tunnel is torn down when the relay exits — including on hard kill (the bridge holds ssh's stdin open for exactly this reason).

Development

The package files under bin/ are byte-identical copies of the repo's bin/mcp-bridge.js, bin/mcp-bridge-ssh.js, and bin/utils/env-file.js — the repo bin/ is canonical. Edit there, then:

bash
npm run sync               # refresh the copiesnpm run sync -- --check    # drift gate (run in CI)npm test                   # node:test suite (in-process fake endpoint/ssh)npm run pack:dry-run       # inspect the tarball before publishing

Optional Docker E2E against a live NV oOS site (skips when env is unset):

bash
MCP_AI_BASE_URL=http://localhost:8000/wp-json/mcp-ai/v1/mcp \MCP_AI_TOKEN=cred_xxxxx.SECRET \npm run test:e2e

License

GPL-3.0-or-later — see LICENSE.

Source: packages/nvoos-mcp-bridge/README.md at commit 3303988

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.1.0-alpha.4LatestOct 8, 2026