nexus-mcp

TypeScript MCP server for the Plugin Federation Nexus control plane. Coding agents and humans can inspect catalogs, judge opinions, plugins, proposals, and run governance writes — without pasting long-lived Nexus API tokens.

MCP protocol

Item	Value
Spec revision	2026-07-28 (stateless modern core)
TypeScript SDK	@modelcontextprotocol/server@^2 (MCP SDK v2)
Schema validation	Zod v4 (zod/v4)
Transport	stdio (primary); protocol versions advertised include modern + 2025-era fallbacks

Configured in src/mcp-protocol.ts via supportedProtocolVersions (modern 2026-07-28 first).

Security model

Identity	How it authenticates	Nexus credential
Human (Cursor, Claude Desktop, local agent)	GitHub SSO — device flow (GITHUB_OAUTH_CLIENT_ID) or existing gh auth login session	Short-lived Nexus JWT via provider: github_user (memory only)
GitHub Actions / coding agents in GitHub	GitHub OIDC (permissions: id-token: write) + tenant OIDC trust policy	Short-lived Nexus JWT via provider: github_actions (memory only)

Not supported (by design):

• NEXUS_ACCESS_TOKEN / NEXUS_BEARER_TOKEN (static control-plane secrets)
• Gateway enrollment / workload / bootstrap credential tools
• Recording tool catalogs or analyses from chat (CI + OIDC Actions own evidence)

Nexus remains the only issuer of API JWTs (ADR 0008).

Tools (v0.1)

Orientation: get_session, get_tenant, list_pipeline_checks

Plugins: list_plugins, create_plugin, get_plugin_draft, replace_plugin_draft, compose_plugin_draft, list_plugin_variants, list_plugin_revisions

Quality: get_tool_catalog, list_tool_analyses, list_tool_judges, get_tool_judge, create_tool_judge, update_tool_judge, get_latest_schema_verification, summarize_source_quality, find_fix_suggestions_for_tool

Governance: get_proposal, create_proposal, create_proposal_from_schema_verification, decide_proposal (confirm), release_plugin_revision (confirm), promote_plugin_revision (confirm)

Exports: get_compatibility_report, create_export, get_export_job

Audit: list_audit_events

Setup

npm install
npm run build

Environment

Variable	Required	Purpose
NEXUS_URL	yes	e.g. https://api.nonprod.plugin-federation.com
TENANT_ID	Actions OIDC	Tenant UUID matching OIDC trust policy; also preferred tenant for multi-membership humans
NEXUS_OIDC_AUDIENCE	Actions	Must match Nexus NEXUS_OIDC_GITHUB_AUDIENCE (defaults to NEXUS_URL)
GITHUB_OAUTH_CLIENT_ID	humans (device flow)	Public OAuth App client id for device flow
NEXUS_MCP_ALLOW_GH_CLI	no	Default true — use gh auth token when device flow client id unset
NEXUS_MCP_GITHUB_USER_TOKEN	no	Optional GitHub user OAuth token injected by a host (still exchanged; never a Nexus JWT)

Human (local)

# Option A: GitHub CLI already SSO'd
gh auth login
export NEXUS_URL=https://api.nonprod.plugin-federation.com
export TENANT_ID=<optional-preferred-tenant>
npx tsx src/index.ts

# Option B: device flow
export GITHUB_OAUTH_CLIENT_ID=<public-oauth-app-client-id>
npx tsx src/index.ts
# Follow the verification URL + user code on stderr

GitHub Actions / coding agent

permissions:
  id-token: write
  contents: read
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: "22"
  - run: npm ci && npm run build
    working-directory: path/to/nexus-mcp
  - name: Run agent with Nexus MCP
    env:
      NEXUS_URL: ${{ vars.NEXUS_URL }}
      TENANT_ID: ${{ vars.TENANT_ID }}
      NEXUS_OIDC_AUDIENCE: ${{ vars.NEXUS_OIDC_AUDIENCE }}
    run: node path/to/nexus-mcp/dist/index.js

Register owner/repo (immutable ids) on a Nexus OIDC trust policy with the roles the agent needs (contributor / approver / etc.).

MCP client config (stdio example)

{
  "mcpServers": {
    "nexus": {
      "command": "node",
      "args": ["/absolute/path/to/nexus-mcp/dist/index.js"],
      "env": {
        "NEXUS_URL": "https://api.nonprod.plugin-federation.com",
        "TENANT_ID": "11111111-1111-4111-8111-111111111111",
        "GITHUB_OAUTH_CLIENT_ID": "Ov23li…"
      }
    }
  }
}

Development

npm run typecheck
npm run dev

Related

• ADR 0008 Human GitHub SSO
• meteo-static / units-static dogfood MCPs
• Console uses the same github_user exchange path