NV oOS Gateway

io.github.nvdigitalsolutionsPublished by GitHub account nvdigitalsolutionsv0.3.1Updated Nov 4, 2026

Streamable HTTP MCP gateway for NV oOS fleets — one API key, namespaced tools, quotas and policy.

VerifiedStreamable HTTPWeb executableProductivity & WorkflowDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

Remote MCP gateway that exposes the tools of multiple NV oOS WordPress sites behind one API key, with namespaced tool names, quotas and policy.

What you can do
  • List and call tools from every NV oOS WordPress site bound to your key, merged into one namespaced list such as site-a.create_post
  • Run site tools through the gateway, which forwards initialize, tools/list and tools/call to each site's native MCP endpoint
  • Test a call without executing it using a dry-run flag that reports whether policy and quota would allow it
  • Inspect fleet health, the effective policy and quota table, and the per-site catalog through operator-only admin routes
  • Use OAuth 2.1 bearer tokens as an alternative to static keys when the gateway is configured as a protected resource
When to use it
Useful when an assistant needs to work across several NV oOS WordPress sites through a single endpoint and credential, and when you want fleet-level tool quotas, deny or approval rules, and per-site namespacing rather than connecting to each site separately.
Requirements
A remote streamable HTTP endpoint; no local install. Requires an NV Digital Solutions gateway API key bound to one or more site slugs, sent as an Authorization Bearer header. OAuth 2.1 via an external authorization server is an optional alternative. Network access to the gateway and to the bound sites.
Before you install
The key grants access to every site bound to it, so scope and rotate it carefully. Tool calls execute real actions on the WordPress sites, including content and store operations; policy rules can deny or require approval but are configured server-side. Upstream Fleet Operator tokens are held by the gateway, and governance events can be sent to an external audit webhook.

Installation

In SourceWeft

  1. Open NV oOS Gateway in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.nvdigitalsolutions%2Fnvoos-mcp-gateway/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "nv-oos-gateway": {
      "type": "http",
      "url": "https://mcp.nvoos.pro/mcp"
    }
  }
}

README

NV oOS MCP Gateway

==================

[NV oOS MCP Gateway]

A public, fleet-scoped Model Context Protocol endpoint for the NV oOS (Open Operator System) WordPress platform. One API key, every bound site — tools appear namespaced as <site-slug>.<tool>.

The gateway is an MCP aggregating proxy speaking streamable HTTP (MCP 2026-07-28): it authenticates callers with a public API key, forwards initialize / tools/list / tools/call to the bound NV oOS sites' native /wp-json/mcp-ai/v1/mcp endpoints using Fleet Operator tokens, and keeps the fleet surface collision-free by prefixing tool names per site.

Deployment target: Cloudways Velocity (managed Node hosting) at https://mcp.nvoos.pro. See docs/operations/deployment/mcp-gateway-velocity-setup.md.

One-way mirror: this addon is the canonical source and is synced to the standalone repo nvdigitalsolutions/nvoos-mcp-gateway (branch main) by sync-mcp-gateway.yml, which snapshots the subtree as one commit per sync and pushes without --force — the mirror main stays a linear fast-forward line, so hosting platforms (Cloudways Velocity) auto-deploy on every sync. Never commit to the standalone repo directly — the next sync overwrites it.

Endpoints

RouteAuthPurpose
GET /mcppublicStreamable-HTTP discovery JSON
POST /mcpBearer keyJSON-RPC 2.0 (initialize, ping, notifications, tools/list, tools/call, resources/, prompts/)
GET /healthpublicMinimal status + per-site health registry
GET /health/fullBearer keyFull view (host-only URLs, bindings)
GET /admin/policyOperator tokenEffective policy + quota table (read-only)
POST /admin/policy-simOperator tokenReplay a candidate policy against recorded calls
GET /admin/catalogOperator tokenFleet catalog with per-site lifecycle states
GET /publicHuman landing page (directory reviewers)

Configuration (env only)

VariableRequiredPurpose
GATEWAY_PUBLIC_KEYSyesPublic keys → site slugs: key=slug-a,slug-b;key2=slug-c (or JSON object)
GATEWAY_PUBLIC_KEYS_PREVIOUSnoRotation overlap — previous key map (warns once on use)
PUBLIC_SITE_SLUGSnoPrivacy filter for the public /health endpoint: comma-separated slugs visible without auth (* or unset = all configured sites). /health/full always reports every site.
NVOOS_SITE_<SLUG>_URLper siteUpstream MCP endpoint, full URL incl. /wp-json/mcp-ai/v1/mcp
NVOOS_SITE_<SLUG>_TOKENper siteFleet Operator token (op_xxxx.SECRET); never logged or returned
AUTH_MODEnostrict (default) fails closed at boot when no keys are set
UPSTREAM_TIMEOUT_MSnoPer-site timeout for tools/list + notifications (default 20000)
UPSTREAM_TOOL_TIMEOUT_MSnotools/call budget only — long-running tools get more room without slowing tools/list (default: UPSTREAM_TIMEOUT_MS)
GATEWAY_OAUTH_ISSUERnoOAuth 2.1 authorization server issuer (e.g. Auth0 tenant). Setting it turns the gateway into an RFC 9728 protected resource — see the OAuth section below
GATEWAY_OAUTH_JWKS_URInoJWKS override (default: issuer's /.well-known/jwks.json)
GATEWAY_OAUTH_RESOURCEnoRFC 8707 resource identifier / token audience (default https://mcp.nvoos.pro)
TRUST_PROXYyes on Velocity1 — NGINX sets X-Forwarded-For
ALLOWED_ORIGINSnoComma-separated CORS origins for browser-based clients
MAX_JSON_BODYnoBody limit (default 1mb)
RATE_LIMIT_GLOBAL / _MCP / _HEALTHnoPer-group budgets (defaults 600/5min, 120/min, 60/min)
TOOL_QUOTASnoPer-tool quotas, compact form: <pattern>:<rate>/<window>:<burst> — e.g. delete_post:5/1h:2,woo_*:60/1m:*. Most-specific pattern wins. (Proposal 094)
GATEWAY_POLICYnoPolicy ruleset (JSON string) — see the policy reference below. (Proposal 094)
POLICY_FILEnoAlternative: path to a JSON policy file (Git-versioned policy, read at boot).
SHADOW_POLICYnoShadow ruleset (JSON string) — evaluated and logged, never enforced.
GEO_MAPnoJSON object mapping public key ids to ISO country codes (used when not behind a trusted proxy).
GATEWAY_ADMIN_TOKENnoOperator token enabling the /admin/* surface (inert without it).
AUDIT_SINK_URL / AUDIT_SINK_SECRETnoHMAC-signed webhook for governance events (deny, quota_exceeded, call_ok…). Must be set together.
SITE_LIFECYCLEnoPer-site catalog states: slug-a:draft,slug-b:published (default published).

Slug → env suffix mapping: site-a → NVOOS_SITE_SITE_A_* (uppercase, hyphens → underscores).

Example

env
GATEWAY_PUBLIC_KEYS=demo-public-key-1234567890=demo-siteNVOOS_SITE_DEMO_SITE_URL=https://demo.example.com/wp-json/mcp-ai/v1/mcpNVOOS_SITE_DEMO_SITE_TOKEN=op_xxxx.SECRETAUTH_MODE=strictTRUST_PROXY=1

Policy & quotas (Proposal 094)

Per-tool quotas and declarative policy ride on top of the group budgets. Sites remain the deep enforcement layer (per-tool RPM, token budgets, iteration caps, capability boundaries, nefarious-usage auto-shutdown) — the gateway adds the fleet layer and can only tighten, never weaken.

Quotas

env
TOOL_QUOTAS=delete_post:5/1h:2,woo_*:60/1m:*,*:600/5m:*

Breaches return HTTP 429 + RFC 9558 headers (RateLimit-Limit/Remaining/Reset, RateLimit-Policy) with the JSON-RPC error -32099. Buckets are scoped (key × site × tool) — one noisy key cannot exhaust another's budget.

Policy grammar

json
{  "rules": [    {      "id": "no-night-deletes",      "effect": "deny",      "tool": { "match": "delete_*" },      "time": { "window": { "tz": "Europe/London", "days": [1,2,3,4,5], "start": "09:00", "end": "17:00" } }    }  ]}

First match wins. Effects: deny (403 + -32001), require_approval (428 + -32002 with a redacted preview). Conditions: tool.match (glob), site, key, time.window (IANA tz, ISO weekdays 1–7, midnight-crossing windows), geo.country (ISO alpha-2). Denied tools are filtered out of tools/list entirely (kept out of model context).

Inspection

  • dryRun: true on tools/call evaluates policy + quotas without executing or consuming — the result carries would_execute, policy, and quota.
  • POST /admin/policy-sim replays a candidate policy against the last 200 recorded calls (argument keys only) and diffs it against the live policy.
  • SHADOW_POLICY evaluates in parallel and logs — never enforces.

Tool namespacing

  • tools/list merges every site bound to the key and prefixes names: site-a.create_post, site-b.woo_get_products.
  • tools/call accepts the prefixed name (always) or a bare name when the key is bound to exactly one site (passthrough mode).
  • A failing upstream degrades the list to a _meta.gateway.errors entry instead of failing the whole call.
  • v1 aggregation limitation: resources/* and prompts/* use the first bound site.

Behavior & security

  • Protocol negotiation: initialize echoes the highest protocol version both sides support (2026-07-28 → 2024-11-05), defaulting to 2024-11-05 when the client sends no version — strict clients (Zed, Claude Desktop) abort with "Unsupported protocol version" when the server hardcodes a version they do not speak.
  • Stateless — no sessions, no SSE in v1 (the July 2026 spec revision makes stateless transport first-class).
  • Fail-closed: no keys configured in strict mode → boot refuses; a key bound to no configured site → 503; unknown key → 401 with WWW-Authenticate.
  • Rate limits are per public key (one noisy key cannot exhaust another's budget); upstream tokens are header-only and never appear in responses, logs, or errors.
  • Auth: static API keys in v1; OAuth 2.1 (RFC 8414 + dynamic client registration) is the documented upgrade path.

Claude Code plugin

The addon ships a Claude Code plugin (.claude-plugin/plugin.json, commands/connect.md, skills/gateway/) that syncs to the mirror repo and doubles as the marketplace source:

/plugin marketplace add nvdigitalsolutions/nvoos-mcp-gateway

Enabling the plugin prompts for the gateway API key (stored securely as a sensitive userConfig option) and substitutes it into the MCP server's Authorization header.

OAuth 2.1 resource server (opt-in)

With GATEWAY_OAUTH_ISSUER set, the gateway acts as an RFC 9728 protected resource alongside static keys:

  • GET /.well-known/oauth-protected-resource (+ the /mcp path-insertion variant) serves the protected-resource metadata document (inert 404 when OAuth is unconfigured).
  • 401 responses carry WWW-Authenticate: Bearer resource_metadata="…", scope="…" so MCP clients can run the OAuth 2.1 authorization-code + PKCE flow against the configured authorization server.
  • JWT bearer tokens validate against the AS JWKS (cached, fail-closed): signature, iss, aud (RFC 8707 resource binding), exp/nbf, and scope.
  • Site binding is scope-based: each site:<slug> scope grants access to that bound site (the read-only site:read scope is advertised for future fine-grained enforcement). Tokens granting no configured site get 403 insufficient_scope.
  • Upstream proxying is unchanged: the gateway always exchanges for the site's own Fleet Operator token — OAuth tokens are never forwarded upstream (no confused-deputy passthrough).

Authorization server: any OAuth 2.1 AS with RFC 8414 metadata + JWKS (Auth0 is the platform convention). Dynamic client registration (RFC 7591) belongs to the AS, not the gateway.

Development

bash
npm installnpm test        # node:test suites — fake upstreams, no infrastructurenpm run dev     # node --watch src/index.js

Local smoke test against the docker compose dev site:

bash
GATEWAY_PUBLIC_KEYS="dev-key-1234567890abcd=docker" \NVOOS_SITE_DOCKER_URL="http://localhost:8000/wp-json/mcp-ai/v1/mcp" \NVOOS_SITE_DOCKER_TOKEN="<assistant/operator token>" \PORT=8899 npm start# → curl http://127.0.0.1:8899/mcp

Ecosystem discovery

The public endpoint https://mcp.nvoos.pro/mcp is listed in the official MCP Registry (registry.modelcontextprotocol.io) as io.github.nvdigitalsolutions/nvoos-mcp-gateway — a streamable-HTTP remote with a required Authorization header. The registry metadata lives in server.json and is published with the mcp-publisher CLI. Community directories (mcpservers.org, mcp.directory, PulseMCP, Glama) carry entries that point back here; the GET / landing page is the directory-reviewer surface.

License

GPL-3.0-or-later — see the repository LICENSE.

Source: addons/mcp-gateway/README.md at commit a11903e

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

3
  1. v0.3.1LatestNov 4, 2026
  2. v0.3.0Nov 3, 2026
  3. v0.2.0Nov 1, 2026

Score

75% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.