@omega-protocol/mcp-server

OMEGA Protocol substrate and governed decision capabilities exposed through the Model Context Protocol. Validates upstream responses against omega-record.schema.json v1.0 from @omega-protocol/contracts and surfaces typed errors with structured codes.

What you get

| Surface | Name | Purpose | |---------|------|---------| | Tool | omega_substrate_status | Read omega-data substrate status + supported native record types. | | Tool | omega_compose_native_record | Compose a supported native domain record into an OmegaRecord via omega-data. | | Tool | omega_submit_decision | Submit a governed decision to the OMEGA Decision API. | | Tool | omega_get_decision | Retrieve a governed decision record by mandate or decision id. | | Resource | omega://agent-metadata | Static OMEGA Protocol metadata (no network call). | | Prompt | omega_precommit_decision | Template for preparing a governed decision payload. |

The initial substrate scope is trade_decision native records through omega-data. The server does not invent capabilities outside the omega-contracts schemas.

Install

From npm (once published):

npm install -g @omega-protocol/mcp-server

From a local clone:

cd omega-mcp-server
npm install
npm run build
node dist/index.js

Requires Node.js >=20.

Configure

MCP client (Claude Desktop, Cursor, Claude Code, etc.)

{
  "mcpServers": {
    "omega-governance": {
      "command": "npx",
      "args": ["-y", "@omega-protocol/mcp-server"],
      "env": {
        "OMEGA_DATA_URL": "http://localhost:3100",
        "OMEGA_DECISION_API_URL": "https://omega-governance-api-production.up.railway.app",
        "OMEGA_REQUEST_TIMEOUT_MS": "30000"
      }
    }
  }
}

Environment variables

| Name | Required | Default | Notes | |------|----------|---------|-------| | OMEGA_DATA_URL | no | http://localhost:3100 | Base URL for omega-data. Must be http: or https:. | | OMEGA_DECISION_API_URL | no | production Decision API | Base URL for the OMEGA Decision API. Must be http: or https:. | | OMEGA_API_URL | no | — | Backward-compatible alias used when OMEGA_DECISION_API_URL is unset. | | OMEGA_REQUEST_TIMEOUT_MS | no | 30000 | Per-request timeout, milliseconds. Allowed range: 1000–300000. |

Invalid values raise OMEGA_CONFIG_ERROR at server startup; the server refuses to start rather than running with a broken config.

Tools

omega_substrate_status

Read-only. No arguments. Returns the upstream GET /substrate/status response, validated to contain at least { status: string }.

{
  "name": "omega_substrate_status",
  "arguments": {}
}

Sample response:

{
  "status": "ok",
  "supported_native_record_types": ["trade_decision"]
}

omega_compose_native_record

Compose a supported native record into a canonical OmegaRecord through omega-data.

Input schema:

| Field | Type | Constraint | |-------|------|------------| | record_type | string | matches /^[a-z][a-z0-9_]{1,63}$/. Initially only trade_decision. | | native_record | object | the native domain record |

Example:

{
  "name": "omega_compose_native_record",
  "arguments": {
    "record_type": "trade_decision",
    "native_record": {
      "record_id": "trade-001",
      "decision": "hold"
    }
  }
}

Sample envelope (response):

{
  "inserted": true,
  "omega_record_id": "omega:trade:1",
  "omega_record": {
    "record_id": "...",
    "schema_version": "omega/1.0",
    "...": "..."
  }
}

If omega_record is present, it is validated against omega-record.schema.json v1.0 before the envelope is returned.

omega_submit_decision

Submit a governed decision to the Decision API (POST /decisions).

Input schema:

| Field | Type | Constraint | |-------|------|------------| | decision | object | request body for POST /decisions |

Example:

{
  "name": "omega_submit_decision",
  "arguments": {
    "decision": {
      "mandate_id": "M-2026-05-26-001",
      "subject": {
        "domain": "trade.spot",
        "action": "Submit GBP/USD market order",
        "actor_id": "agent-alpha",
        "stakes": "high"
      },
      "governance": { "authorised_agent": "agent-alpha" }
    }
  }
}

Sample response:

{
  "status": "COMMITTED",
  "mandate_id": "M-2026-05-26-001",
  "omega_record": { "schema_version": "omega/1.0", "...": "..." }
}

Embedded OmegaRecord (if present) is validated against schema v1.0.

omega_get_decision

Retrieve a governed decision record.

Input schema:

| Field | Type | Constraint | |-------|------|------------| | id | string | matches /^[A-Za-z0-9_\-./:]{1,256}$/. URL-encoded into the path. |

Example:

{ "name": "omega_get_decision", "arguments": { "id": "M-2026-05-26-001" } }

Sample response (a full OmegaRecord, validated against schema v1.0):

{
  "record_id": "01HZX2K8Q7...",
  "schema_version": "omega/1.0",
  "contracts_version": "0.2.2",
  "subject": { "domain": "...", "action": "...", "actor_id": "...", "stakes": "high" },
  "outcome": { "gate_result": "COMMITTED", "gate_reason": "...", "acted": true },
  "previous_hash": "...",
  "content_hash": "..."
}

Errors

Every error returned by a tool is a JSON object with this shape:

{
  code: "OMEGA_CONFIG_ERROR" | "OMEGA_INPUT_ERROR" | "OMEGA_TRANSPORT_ERROR" |
        "OMEGA_UPSTREAM_ERROR" | "OMEGA_SCHEMA_ERROR";
  message: string;
  status?: number;        // present on OMEGA_UPSTREAM_ERROR
  details?: unknown;      // structured context (ajv errors, URL, etc.)
}

The tool result has isError: true and a single text content item containing the JSON error envelope. Example:

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "{\n  \"code\": \"OMEGA_UPSTREAM_ERROR\",\n  \"message\": \"OMEGA HTTP 503 ...\",\n  \"status\": 503,\n  \"details\": { ... }\n}"
  }]
}

Error code reference

| Code | When | What the client should do | |------|------|---------------------------| | OMEGA_CONFIG_ERROR | Bad env var (invalid URL, out-of-range timeout) | Fix config and restart. | | OMEGA_INPUT_ERROR | Tool arguments fail input schema | Fix arguments. Don't retry verbatim. | | OMEGA_TRANSPORT_ERROR | Network failure, DNS, timeout, aborted request | Retry with backoff. | | OMEGA_UPSTREAM_ERROR | Non-2xx HTTP response from omega-data or Decision API | Check status; consult upstream logs; retry on 5xx, fix on 4xx. | | OMEGA_SCHEMA_ERROR | Upstream returned a payload that fails OmegaRecord v1.0 validation | Report to omega-data / Decision API maintainer; do not silently retry. |

Schema reference

This package vendors a frozen snapshot of the schemas from @omega-protocol/contracts v0.2.2 under src/schemas/. A drift test (tests/schema-drift.test.ts) compares the snapshot byte-for-byte against the upstream source when run inside the monorepo.

| Schema | $id | |--------|-------| | OmegaRecord | https://omegaprotocol.org/schemas/omega-record.schema.json | | ProtocolId | https://omegaprotocol.org/schemas/protocol-id.schema.json | | ClearpathSummary | https://omegaprotocol.org/schemas/clearpath-summary.schema.json | | CognitiveProfile | https://omegaprotocol.org/schemas/cognitive-profile.schema.json | | ConsentRecord | https://omegaprotocol.org/schemas/consent-record.schema.json | | HarmRecord | https://omegaprotocol.org/schemas/harm-record.schema.json | | AssumptionGate | https://omegaprotocol.org/schemas/assumption-gate.schema.json | | DisputeFinding | https://omegaprotocol.org/schemas/dispute-finding.schema.json | | EthicsReview | https://omegaprotocol.org/schemas/ethics-review.schema.json | | TrustScore | https://omegaprotocol.org/schemas/trust-score.schema.json | | DerivedFieldProvenance | https://omegaprotocol.org/schemas/derived-field-provenance.schema.json |

OmegaRecord required fields

{
  record_id: string,
  schema_version: "omega/1.0",   // const
  contracts_version: string,
  created_at: string,
  subject: {
    domain: string,
    action: string,
    actor_id: string,
    stakes: "low" | "moderate" | "high" | "critical"
  },
  outcome: {
    gate_result: "COMMITTED" | "HELD" | "ESCALATED",
    gate_reason: string,
    acted: boolean,
    non_action_record?: string,
    blocked_by?: ProtocolId
  },
  previous_hash: string | null,
  content_hash: string   // 64-char lowercase hex
}

Optional protocol slots: clearpath, cognitive, consent, harm, assumption, dispute, ethics, trust, provenance, signature.

Worked examples

Three load-bearing scenarios live under docs/examples/:

| File | Scenario | |------|----------| | 01-gate-high-stakes-action.json | An agent calls omega_submit_decision before a £12.5k trade and proceeds only on gate_result === "COMMITTED". | | 02-record-decision-chain.json | A 3-step assess → execute → reconcile chain with previous_hash linkage (P3 / P_ChainIntegrity). | | 03-attestation-for-external-auditor.json | A compliance tool calls omega_get_decision and surfaces the schema-validated OmegaRecord to an external auditor. |

Each example shows the tool call, the expected response, and what the server does internally.

Troubleshooting

"OMEGA HTTP 404 …" for omega_substrate_status

omega-data is not running at OMEGA_DATA_URL. Start it locally or point at a running instance:

curl -fSs "$OMEGA_DATA_URL/substrate/status"

"Request timed out after 30000ms"

The upstream is slow or the network is unreachable. Either:

• Increase OMEGA_REQUEST_TIMEOUT_MS (cap is 300000).
• Investigate the upstream service.

OMEGA_SCHEMA_ERROR on every Decision API call

The Decision API is returning a payload that doesn't validate against omega-record.schema.json v1.0. This is a service-side regression; capture the details.value and details.errors from the error envelope and file an issue upstream. Do not bypass the validation.

MCP error -32602: Invalid arguments

Your MCP client sent arguments that fail the tool's input schema. Inspect the schema via tools/list and adjust. Common cases:

• record_type must be lowercase snake_case.
• id must match /^[A-Za-z0-9_\-./:]{1,256}$/.
• decision must be a plain object.

Security considerations

• No secrets are logged. Errors include URLs and response bodies but never request bodies — if a decision payload contains sensitive fields, treat the upstream Decision API as the trust boundary, not this server.
• Base URLs are scheme-restricted to http: and https:. Attempts to configure file:, data:, or javascript: URLs raise OMEGA_CONFIG_ERROR.
• Request timeout is bounded to 300000 ms. A misconfigured client cannot hold a server-side request open indefinitely.
• Output is schema-validated. A compromised or buggy upstream cannot leak arbitrary payloads through this server as if they were OmegaRecords; the validator catches them.
• No auth is layered on top of the upstream APIs by this server. If the Decision API requires authentication, configure it in the upstream service and rely on TLS for transport.

Development

npm install
npm run check          # tsc --noEmit, strict
npm test               # full suite via node --test
npm run test:coverage  # c8, enforces ≥90% line/branch/function
npm run build          # tsc -p tsconfig.build.json + copy-schemas

See CONTRIBUTING.md for the contribution flow and CHANGELOG.md for release history.

License

MIT © WRKS Holdings Ltd.

Registry

This package targets the official MCP Registry under namespace org.omegaprotocol. The registry manifest is server.json. Publishing requires namespace authentication via the registry publisher flow.