@vorionsys/mcp-server

Model Context Protocol server exposing Vorion audit and trust primitives — local trust scoring, proof logging, and remote Cognigate Runtime tools.

This server lets MCP clients (Claude Desktop, Cursor, IDEs, agent frameworks) call Vorion audit and trust primitives directly: check an agent's trust tier, record behavioral signals, run pre-flight tier checks for actions, log proof-chained decisions, and — when configured with a deployed Cognigate Runtime endpoint — submit canary probes, tail tenant audit streams, and perform health checks against a live runtime. Pre-flight checks return a decision; honoring that decision is up to the calling client.

BASIS is to AI-agent governance what OAuth is to delegated authorization — an open standard so an agent trusted by one system can be evaluated by another.

Status: source-available / reference use. This repository is the canonical home for the Vorion MCP server. The npm package @vorionsys/mcp-server and its runtime dependencies are currently withdrawn pending IP review (see Install / current status). Use it as a reference for how a governance layer is exposed over MCP, and as the source you build from once the dependency chain is published.

---

Quick start (one command to clone + build)

The published npm package is withdrawn (see below), so install from this repo:

# Clone, install, build — then the stdio entrypoint is dist/index.js
git clone https://github.com/voriongit/mcp-server.git && cd mcp-server && npm install && npm run build

The build produces an executable stdio server at dist/index.js (the package also exposes it as a vorion-mcp bin). To run it directly once built:

node dist/index.js

Or run from source without building (uses tsx):

npm run dev

The server speaks the Model Context Protocol over stdio — it does not print to stdout except MCP frames, and it does not open a port. It is meant to be launched by an MCP client (see Use with Claude Desktop), not run interactively.

Heads-up before you run it: a clean public install does not boot yet. The runtime depends on @vorionsys/sdk, which pulls a chain of @vorionsys/* packages that are withdrawn pending IP review — so the server currently exits at startup with ERR_MODULE_NOT_FOUND. See Troubleshooting for exactly what you'll see and why.

---

What trust signals you get

When an MCP client wires this server in, your agent's tool calls can be governed instead of blindly executed. In practice you get:

• A trust score and tier per agent (0–1000, mapped to tiers T0–T7) so a client can decide how much autonomy an agent has earned — not just whether a single call looks safe.
• A pre-flight allow/deny (vorion_gate_action / vorion_execute_governed) that checks an agent's tier against the risk of an action before it runs.
• Behavioral feedback that moves the score — successes raise trust, failures lower it, and higher-tier agents are penalized more for failures (penalty formula P(T) = 3 + T).
• A hash-chained proof log of every ALLOW/DENY decision, so the reasoning behind a governed action is auditable after the fact.
• (Optional, remote) tenant + canary visibility against a deployed Cognigate Runtime: who an API key resolves to, a tail of the hash-chained audit stream, and a place to submit canary-probe outcomes.

These are governance signals for a client to act on — they don't themselves block your OS or network; enforcement is up to the client that consumes them.

---

What's in the box

Local trust-engine tools (run locally, no API key)

Tool	Purpose
vorion_check_trust	Look up an agent's score (0–1000), tier (T0–T7), and observation tier.
vorion_record_signal	Record a behavioral signal (behavioral.success / behavioral.failure / compliance.pass / compliance.fail).
vorion_gate_action	Pre-flight check: does the agent meet the required tier for an action?
vorion_log_proof	Log an ALLOW/DENY decision to the hash-chained proof log.
vorion_execute_governed	Gate + record signal + log proof in one call (recommended).

Remote Cognigate Runtime tools (require VORION_API_URL + VORION_API_KEY)

Tool	Purpose
vorion_tenant_whoami	Resolve the calling API key to its tenant id, role, and capabilities.
vorion_tenant_list	List all tenants on the runtime (admin-only).
vorion_tenant_audit_tail	Tail recent hash-chained audit events for a tenant.
vorion_canary_submit	Submit a canary probe result (pass / fail / ambiguous) to the runtime.
vorion_health_check	Hit the configured Cognigate Runtime /api/v1/health endpoint.

Without VORION_API_URL + VORION_API_KEY, the remote tools still appear in the surface but return a structured not configured error — the local trust-engine tools are unaffected.

Resources

• vorion://tiers — the BASIS 8-tier trust model (score ranges, capabilities, penalty multipliers, penalty formula).
• vorion://agents/{agentId}/trust — current trust profile for a specific agent.

---

Telemetry & privacy

Read the source if you want to confirm any of this — it is all in src/index.ts.

• The five local trust-engine tools make no network calls. They run entirely in-process against the local trust engine and an in-memory proof log. Nothing is sent anywhere.
• No analytics, no usage telemetry, no crash reporting. There is no Sentry/PostHog/"phone-home" code path. The only thing written to a remote service is the explicit remote-tool calls you make.
• The only outbound network calls come from the five remote tools, and only when both VORION_API_URL and VORION_API_KEY are set. In that case the server makes HTTPS requests to the Cognigate Runtime URL you configure (e.g. your own deployment), sending your VORION_API_KEY as a Bearer token and the arguments you passed to the tool. If those env vars are unset, no outbound request is ever attempted.
• The server logs only to stderr, and only on a fatal startup error. It does not log tool inputs/outputs.

In short: with no env vars configured, this is a fully local server with no telemetry. Any network traffic is an explicit remote tool call to an endpoint you chose.

---

Install / current status

Do not npm install @vorionsys/mcp-server. That package — along with its runtime dependencies @vorionsys/sdk and @vorionsys/proof-plane — is currently deprecated on npm with the message "withdrawn pending IP review." Install from this repository instead (see Quick start).

Because the dependency chain is mid-review, a clean public clone will install and build but will not yet boot at runtime (the SDK imports withdrawn private @vorionsys/* peers that npm cannot resolve). Treat this repo as reference / source-available until those packages are published. See Troubleshooting.

---

Use with Claude Desktop

Because the npm package is withdrawn, point Claude Desktop at your locally built copy rather than npx-ing the published package. After running the Quick start, add the following to claude_desktop_config.json (use the absolute path to your clone's dist/index.js):

{
  "mcpServers": {
    "vorion": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
    }
  }
}

To enable the remote Cognigate Runtime tools (vorion_tenant_whoami, vorion_tenant_list, vorion_tenant_audit_tail, vorion_canary_submit, vorion_health_check), add the two environment variables, pointing VORION_API_URL at your runtime deployment:

{
  "mcpServers": {
    "vorion": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "VORION_API_URL": "https://your-cognigate-runtime.example.com",
        "VORION_API_KEY": "vrn_live_..."
      }
    }
  }
}

The server is registered under the name vorion, so its tools appear as vorion_* in the client. VORION_API_URL and VORION_API_KEY are the only two environment variables the server reads.

---

Troubleshooting

The three most common setup failures, in order of likelihood:

1. Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@vorionsys/...' at startup. This is expected today on a clean public install. @vorionsys/sdk pulls a chain of @vorionsys/* packages (e.g. atsf-core, security, a3i, runtime) that are withdrawn pending IP review and therefore cannot be resolved from the public npm registry. The build (npm run build) succeeds, but node dist/index.js exits immediately. There is no public workaround until those packages are published — this is why the repo is currently labeled reference / source-available. If you have access to the Vorion monorepo, install/link those peers there and run from that workspace.

2. The server starts but immediately exits, or your client says "node: command not found" / a syntax error. Check your Node version: node --version. This server requires Node.js >= 20 (it uses native ESM and the global fetch). On older Node you'll see module-resolution or fetch is not defined errors. Also make sure you ran npm run build first — args in the Claude Desktop config must point to the compiled dist/index.js (or use npm run dev for the tsx source path), not src/index.ts directly.

3. The remote tools return Remote Cognigate API is not configured (or a network error). The five remote tools require both VORION_API_URL and VORION_API_KEY to be set in the server's env. If either is missing you'll get a structured not configured error — that's by design, and the local tools keep working. If both are set but you get a network error, the URL is unreachable from where the server runs; if you get 403 on vorion_tenant_list, your key lacks the admin role. Note this is a stdio server: it must be launched by an MCP client (or piped JSON-RPC), not run as an interactive command — a bare node dist/index.js in a terminal will just wait silently for stdin.

---

Development

# Install dependencies
npm install

# Build (tsc -> dist/)
npm run build

# Run tests (vitest)
npm test

# Typecheck only
npm run typecheck

# Run from source over stdio (tsx)
npm run dev

---

Stack

• Runtime: Node.js >= 20, ES modules (type: module).
• Language: TypeScript 5.x, strict mode, NodeNext resolution.
• MCP SDK: @modelcontextprotocol/sdk ^1.28.
• Vorion deps: @vorionsys/sdk ^0.3.1 (local trust engine) and @vorionsys/proof-plane ^0.1.4 (hash-chained event log) — both withdrawn pending IP review on npm; see Install / current status.
• Schema validation: zod.
• Test runner: vitest.
• Transport: stdio (Claude Desktop, Cursor, etc.). HTTP transport is not implemented.

---

Provenance

This package was extracted from the Vorion monorepo at commit 3d7ed92d (April 20 2026 — feat(mcp-server): add remote Cognigate Runtime tools (v0.3.0)).

The remote-runtime work was originally captured in the now-superseded PR voriongit/vorion#137. That PR is closed in favor of this standalone repo per founder direction (Apr 24 2026).

License normalized from UNLICENSED to Apache-2.0 at extraction time.

---

License

Apache-2.0 — see LICENSE.

Copyright 2026 Vorion LLC. See NOTICE for attribution.

---

Links

• Vorion: https://vorion.org
• BASIS specification: https://github.com/voriongit/basis-spec-docs
• Issues: https://github.com/voriongit/mcp-server/issues