MCP gateway

The Definite MCP gateway (definite-mcp-gateway, Node 20+) connects MCP-speaking agent hosts to your existing MCP tool servers while recording provenance-safe telemetry into a Definite workflow run.

It is a pass-through with a ledger trail, not an authorizer:

On tools/list it fans out to every configured upstream server and republishes each tool as upstreamName__toolName.
On tools/call it records a running event, invokes the upstream tool, then records completed or failed.
Telemetry events carry the agent, principal, session, tool name, invocation ID, duration, and the names of the arguments — tool arguments and results are never copied into telemetry.
Deterministic checking is deliberately outside the gateway: agents working through it never emit PASS, FAIL, or CANNOT_VERIFY. Verdicts come only from the deterministic engine when the run is checked.

If telemetry ingestion fails, the tool call returns an error to the host rather than proceeding unrecorded.

Run it

The gateway ships as the definite-mcp-gateway npm package (with a Docker image on Node 22); ask your Definite contact for access if your registry does not resolve it yet.

definite-mcp-gateway --config definite.mcp.json

Field	Type	Required	Description
--config	path	No	Config file path. Default ./definite.mcp.json.
--transport	stdio \| http	No	Default stdio. HTTP serves streamable MCP at /mcp.
--port / --host	number / string	No	HTTP transport bind. Defaults 3456 and 127.0.0.1.
--auth-mode	static \| per_session	No	Static uses one Vault API key for the process. Per-session (HTTP only) requires Authorization: Bearer per request.

Configuration

The config file names the Definite run to attribute telemetry to and the upstream tool servers to expose:

{
  "vault_url": "https://vault.example.com",
  "tenant_id": "your-tenant",
  "run_id": "run_01j...",
  "agent_id": "close-agent",
  "upstreams": [
    { "name": "erp", "type": "http", "url": "https://mcp.example.com/erp" },
    { "name": "sheets", "type": "mcp-stdio", "command": "npx", "args": ["sheets-mcp"] }
  ]
}

Environment variables mirror the config: DEFINITE_VAULT_URL, DEFINITE_VAULT_API_KEY, DEFINITE_AGENT_ID, DEFINITE_PRINCIPAL_ID, DEFINITE_TENANT_ID, DEFINITE_RUN_ID, DEFINITE_MCP_TRANSPORT, DEFINITE_MCP_PORT, DEFINITE_MCP_HOST, and DEFINITE_MCP_AUTH_MODE.

HTTP upstreams must use HTTPS and are blocked from loopback, link-local, and private-range addresses outside development. In per_session mode, each request supplies its own Vault API key, with optional X-Definite-Principal-Id, X-Definite-Agent-Id, X-Definite-Tenant-Id, and X-Definite-Run-Id headers.

What it never does

The gateway does not approve, deny, or rewrite tool calls, does not store tool inputs or outputs, and does not write to your source systems. It exists so that agent tool activity during a workflow run is attributable in the same run record your reviewers and auditors already read.