Marrow SDK MCP server
Commit Oct 27, 2026Provides a runtime control and proof layer for AI agents to gate risky actions and verify outcomes with evidence.
Also known as getmarrow/marrow-sdk
- Stars
- 7
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 27, 2026
- License
- MIT
What is Marrow SDK MCP?
Marrow SDK provides a runtime control and proof layer for AI agents to gate risky actions and verify outcomes with evidence.
Summary generated from the project's README
About Marrow SDK MCP server
Developers building AI agents can use this Node.js and TypeScript SDK to implement a runtime control and proof layer that manages risky operations. By integrating the marrow-sdk into an agent process, teams can establish pre-action policy gates and require owner approvals before sensitive tasks are executed. The system works by intercepting intended actions and checking them against defined risk policies, such as blocking high-risk activities or holding them for manual review.
Once an action is performed, the SDK helps verify the outcome through completion evidence and lifecycle receipts. This ensures that the agent's results are backed by actual measurements rather than just reported intent. Users can configure the client using a MARROW_API_KEY and manage different risk levels through the runGuarded method. The tool is designed for those who own the agent process and need to ensure accountability, provide decision traces, and capture evidence of successful or failed completions in a structured way.
What you can do with it
- 1Requiring manual owner approvalHold an agent's action until a human owner reviews the decision and provides an approval receipt.
- 2Verifying agent task completionEnsure that an agent's reported success is tied to actual measured outcomes through completion evidence.
- 3Monitoring model usage costsAttach compact token and cost counts to an action commit to track model-cost usage evidence.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablegetmarrow/marrow-sdk is public and reachablegithub.com/getmarrow/marrow-sdk ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-27github.com/getmarrow/marrow-sdk ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@getmarrow/sdk
Marrow checks risky AI agent actions before they run and proves what happened afterward.
Marrow is the runtime control and proof layer for teams running AI agents. @getmarrow/sdk is the Node.js and TypeScript client for that layer: use it when you own the agent process and need pre-action policy gates, owner approvals, proof-backed completion, passive outcome capture, and tenant-scoped fleet learning in code.
Current version: 3.7.67. See What's New in v3.7.67. Older release notes are in the changelog.
Contents
- Install
- Quick Start
- Guarded Runs
- Passive Runtime
- Lifecycle Receipts and Decision Traces
- Agent Disagreement Arbitration
- Coordination: Leases, Proof Packets, and Replay
- Adaptive Policy
- Status, Resilience, and Client Updates
- Model-cost usage evidence
- What's New in v3.7.67
- Configuration
- API Reference
- Context and Workflow Examples
- Agent Discovery
- Security and Data Boundaries
- Troubleshooting
- Documentation
Install
npm install @getmarrow/sdk
For automatic environment detection and setup, use the universal installer:
npx @getmarrow/install activate
The SDK uses the Node.js global fetch. Put your key in MARROW_API_KEY. With marrowFromEnv() it can also come from an owner-only env file; see Environment.
Quick Start
import { MarrowClient, marrowEvidence } from '@getmarrow/sdk';
const marrow = new MarrowClient(process.env.MARROW_API_KEY!, {
agentId: 'deploy-agent',
});
const result = await marrow.runGuarded({
action: 'deploy the production worker',
type: 'deploy',
role: 'deploy',
surfaces: ['repository', 'deployment', 'production'],
riskPolicy: 'block_high',
// deploy() is your function. It must return what it measured, not what you hope is true.
execute: async () => deploy(), // resolves to { deployed: boolean; smokePassed: boolean }
// The callback receives the value execute returned; build evidence only from it.
completionEvidence: async (deployed) => marrowEvidence.deployment({
deployed: deployed.deployed,
smokePassed: deployed.smokePassed,
label: 'production',
}),
// Without classifyResult a returned value is committed as success: true,
// even when the evidence above is failed. Derive it from the same measurements.
classifyResult: (r) => ({ success: r.deployed && r.smokePassed }),
});
if (result.blocked || !result.ok) {
throw new Error(result.summary);
}
classifyResult is required for an honest outcome here. Without it, any value execute returns is committed and closed as success: true, even when completionEvidence is failed. Check result.ok as well as result.blocked before treating the deploy as done.
completionEvidence is a plain value or a function that receives the value execute returned. The adapters trust their inputs, so fixed literals such as deployed: true are recorded as verified even when the deployment failed. Always derive adapter inputs from the result the run produced.
You can also build the client from the environment with marrowFromEnv(), which reads MARROW_API_KEY (or MARROW_KEY) from the process environment and local env files; see Environment.
A successful quickStatus() proves authenticated status connectivity for this configured client and agent identity. It does not prove that every action is intercepted, that passive coverage is certified, or that an unwrapped harness is governed. Measured token savings remain zero until provider-observed usage counts land.
Guarded Runs
runGuarded() is the main control surface. It obtains the runtime and workflow gates, records intent, issues and verifies a permit bound to the authenticated account, key, agent, session, exact action, target, and canonical action surfaces when required, prevents execution when strict policy or permit verification blocks it, and closes the success or failure outcome only after every exact server-required proof field is present. Use the lower-level agentRuntime(), think(), permit, and commit() methods only when your integration preserves the same surfaces through issue and verify and implements the same closure discipline explicitly.
Options on runGuarded() (only action and execute are required):
| Option | Default | Purpose |
|---|---|---|
action, type, role, surfaces, context, project, harness |
Describe the action. role is typically one of deploy, audit, patch, review, general; other strings are accepted. |
|
actionTarget |
Protected resource the permit is bound to, for example repository:environment. |
|
riskPolicy |
'warn' |
'off', 'warn', or 'block_high'. With 'block_high', a gate that does not allow the action stops it. |
useAgentRuntime, useWorkflowGate |
riskPolicy !== 'off' |
Consult the agent runtime gate and the workflow gate. |
riskTolerance, requiresApproval |
Workflow gate tolerance (low, medium, high) and approval flag. |
|
requireActionPermit |
Force a signed action permit for this action even when the gate does not require one. | |
ownerApprovalReceiptId |
A server-issued owner approval receipt. When set on an enforced hold, the SDK skips its own hold stop, requires an action permit, and sends the receipt id with the permit request; the server must verify it. The SDK does not check the receipt itself. A degraded verdict, unavailable gate authority, or riskPolicy: 'block_high' with an allow: false verdict can still stop the run. |
|
correlationId, interventionDisposition, actionChanged |
Link lifecycle receipts and report, with evidence, whether guidance was followed, ignored, or overridden. |
|
provenance, modelUsage |
Decision provenance, and compact token and cost counts to attach to the commit. | |
execute |
The callback that performs the work. It does not run when an enforced runtime gate verdict blocks or holds (a hold is skipped when ownerApprovalReceiptId is set and the permit issues and verifies; see that option), or when the workflow gate blocks or holds under a riskPolicy other than 'off'. Advisory (non-enforced) verdicts run it, and riskPolicy: 'off' skips the gates unless useAgentRuntime or useWorkflowGate is set; even then, under 'off' an enforced runtime verdict, a degraded high-risk or unknown verdict, or a required action permit that fails to issue or verify still stops the run. |
|
completionEvidence |
Evidence attached to the outcome commit; see Completion evidence. | |
classifyResult |
Decide success or failure from the returned value; see below. | |
requireOutcomeClosure |
true |
Close the success or failure outcome. |
includeValueReport, valueReportPeriod |
Also fetch a value report after the run. |
When an API returns a value for an unsuccessful application outcome, use the typed classifyResult(result) option. A classification with success: false preserves the returned value while committing and closing failure truth; the governed fetch adapter uses this for normal HTTP 4xx/5xx Response objects.
Result fields worth checking: ok, blocked, result, failure_type, decision_id, summary, gate_verdict, gate_error, owner_approval, action_permit, permit_verified, permit_closed, outcome_closed, before_action_directive, and intervention_receipt. Match on typed fields such as gate_error.code or owner_approval.state, not on summary strings.
Runtime gate verdicts
runGuarded() reads the runtime gate verdict from fields both runtime response shapes carry: the top-level decision, enforcement_decision and risk_gate_enforced of the slim shape this SDK receives by default, or risk_gate on the expanded shape. The strictest of those fields wins, and both shapes reach the same verdict. The verdict is on result.gate_verdict; readRuntimeGateVerdict(runtime) reads it from a direct agentRuntime() call.
| Runtime verdict | execute() |
Result |
|---|---|---|
block where the plan enforces the gate |
does not run | blocked: true, failure_type: 'policy_block', gate_error (MarrowRuntimeGateBlockedError, code MARROW_RUNTIME_GATE_BLOCKED, with gateReceiptId and reason) |
review_required / owner_approval_required where the plan enforces the gate |
does not run | blocked: true, owner_approval with the gate receipt, the decision Marrow created, and the approval and status endpoints when the server publishes them |
| a verdict the SDK does not recognise, where the plan enforces the gate | does not run | gate_error with code MARROW_RUNTIME_GATE_UNRECOGNIZED |
advisory verdict (risk_gate_enforced: false, for example the Team plan) |
runs; the verdict is reported, not enforced | gate_verdict.enforced: false |
allow, proceed, healthy warn |
runs as before | unchanged |
| degraded verdict for high-risk work, the SDK's high-risk unavailable fallback, or a stale cached verdict | does not run | a block stays a block; otherwise owner_approval with approvable: false when no durable receipt exists or the plan is advisory, so retry when Marrow recovers |
Permit requirements are under Action permits.
const result = await marrow.runGuarded({
action: 'update the weekly customer newsletter',
type: 'update',
execute: async () => sendNewsletter(),
});
if (result.gate_error) throw result.gate_error;
if (result.owner_approval) {
// Not done: the account owner must approve the held gate receipt before this action may run.
console.log(result.owner_approval.gate_receipt_id, result.owner_approval.exact_next_action);
}
With riskPolicy: 'block_high', an expanded risk_gate.allow that is not true (or the same condition read from slim fields) still stops the action. This applies to runGuarded() and to the passive runtime's tool(), command(), deploy(), publish() and governed fetch. orient({ autoWarn: true }) sets shouldPause for enforced blocks and holds on both shapes.
Approvals
Some actions are held for the account owner instead of being allowed or blocked outright. A hold is returned, never resolved, by the SDK:
runGuarded()returnsowner_approvalwithstate: 'owner_approval_required', thegate_receipt_id, thedecision_idMarrow created,approvable,reason,exact_next_action, and theapproval_endpointandapproval_status_endpointwhen the server publishes them.- The owner approves or declines in their own tool: the chat or terminal session where the Marrow MCP server or installer is set up. The SDK has no approve call, so this needs one of them. The Marrow dashboard shows receipts and history; it is not where approvals are made.
- Treat a held action as not done.
exact_next_actionis SDK-authored text; when the server publishesapproval_endpoint, the text for an approvable hold refers to that endpoint and an authenticated dashboard session, which does not match the chat-or-terminal flow above. Use it for the gate receipt and decision ids and the status check, and make the approval in the owner's own tool. When the server publishesapproval_status_endpoint, that endpoint reports whether the owner approved, declined, or let the receipt expire;approval_status_poll_after_mssuggests how often to check. - A held run cannot yet be resumed through
runGuarded(): each guarded run asks the runtime gate again and receives a new gate receipt. PassingownerApprovalReceiptIdis not a documented resume path. If a caller does supply one, the SDK skips its own stop for an enforced hold (a degraded verdict, unavailable gate authority, orriskPolicy: 'block_high'with anallow: falseverdict can still stop it), requires an action permit, and sends the receipt id with the permit request. The SDK does not validate the receipt. The action runs only if the server issues a permit for it and the permit then verifies; the SDK relies on the server to check the receipt when it issues the permit. Whether the server rejects a forged, mismatched, cross-tenant or expired receipt is a server behavior this SDK cannot show. Do not pass a receipt id you did not get from the server. - On advisory plans, or when Marrow's gate authority is degraded and no durable receipt exists, the hold carries
approvable: falsebecause there is no owner approval to wait for. Retry once Marrow recovers.
The SDK never writes, infers or fabricates an owner approval. A server-issued approval receipt is only forwarded to the server with the permit request; the SDK does not verify it itself, and caller-written approval flags are not owner authorization. An owner approval never unlocks a block. A stopped result's before_action_directive.message and before_action_directive.exact_next_action are the SDK's own text, never the server's. Runs that were not stopped keep the server's directive.
Action permits
Before execute() runs, runGuarded() binds the runtime gate to the governed decision, obtains a short-lived signed permit for the exact account, key, agent, session, action, target, and canonical action surfaces, and verifies it once. After execution it closes the permit with exact evidence and the real outcome:
- high-risk, review-required, proof-required, and
block_highwork fails closed if permit verification fails; - permits cannot be replayed across agents, sessions, actions, targets, surfaces, decisions, or runtime gates;
- failures before execution are recorded as non-executed outcomes rather than silently bypassed;
runGuarded()closes its consumed permit with the exact bounded completion evidence; ordinary lifecycle receipts cannot close permits;- lower-risk advisory mode remains available, while callers can set
requireActionPermit: truefor any action.
Action permits are required exactly as in 3.7.64: for a high-risk decision brief, high-risk action text, an expanded risk_gate that is high-risk or proof-required, or requireActionPermit: true. The 3.7.65 gate verdicts add no permit requirement for routine work.
issueActionPermit(), verifyActionPermit(), and closeActionPermit() expose the same three steps for integrations that cannot use runGuarded(). enforcementHeartbeat() submits authenticated client-self-reported hook/configuration telemetry without uploading raw configuration; it does not certify hook integrity or coverage. enforcementCoverage() reports permit completion, bypasses, sidecar freshness, and exact repair steps.
Completion evidence
runGuarded() can attach command, test, deployment, or owner-acceptance evidence through the exported marrowEvidence adapters. A successful run with no evidence attached stays observed_only, and marrowEvidence.command({ exitCode: 0 }) marks an exit code of 0 as verified; required proof still prevents unverified completion. Adapters record the values you pass in, so pass measured results, not literals.
| Adapter | Input |
|---|---|
marrowEvidence.command() |
{ exitCode, label? } |
marrowEvidence.tests() |
{ passed, failed, skipped?, label? } (counts) |
marrowEvidence.deployment() |
{ deployed, smokePassed, rollbackTargetRecorded?, label? } |
marrowEvidence.ownerAcceptance() |
{ accepted, label? } |
marrowEvidence.combine() |
any number of the above; verified only when every part is verified |
The adapters produce bounded proof metadata with an evidence_state of verified, failed, or observed_only. They do not include raw stdout, source code, prompts, credentials, or customer content. Adapter failures are reported separately on completion_evidence_error and never relabel a successful action as failed.
Passive Runtime
For owned Node.js processes, install the passive runtime once:
import { MarrowClient } from '@getmarrow/sdk';
const marrow = new MarrowClient(process.env.MARROW_API_KEY!, {
agentId: 'support-agent',
});
const installed = marrow.createPassiveRuntime().install();
console.log(installed);
Observation mode (default)
The default installation reports fetchControlMode: 'observation_only', governedFetchAvailable: false, governanceEnforced: false, and coverageScope: 'owned_node_process'. It schedules ordered, correlated client-self-reported lifecycle receipts without waiting on Marrow before starting the provider request or returning its response. Observation mode never calls beforeAction(), think(), afterAction(), commit(), or a permit endpoint; it therefore cannot authorize work or create decision/outcome debt. Background lifecycle work is capped and each delivery uses the bounded lifecycle deadline; the durable spool retains receipts that have been enqueued, while queue saturation or process termination before enqueue remains honest missing coverage. Provider token counts are recorded only when the response contains measured usage. Calls outside this process and actions that bypass the patched fetch remain outside that scope. Accepted lifecycle telemetry is not certified coverage or permit closure.
Marrow's own control-plane requests (status, runtime, proof, outcome) stay outside the passive wrapper, so observing application and provider fetches never recursively intercepts the SDK itself.
Unless you pass requireOutcomeClosure: false, installing the runtime registers a beforeExit handler that ends the session and auto-commits open decisions when the Node process exits. Token usage capture can be turned off with captureModelUsage: false or the environment variable MARROW_PASSIVE_TOKEN_USAGE=false.
Use explicit runtime.tool(), .command(), .deploy(), .publish(), or runGuarded() for consequential work. These go through the same gates, permits, and closure as runGuarded().
Governed fetch
If this owned process must place all non-read global fetches on the signed control path, opt in explicitly:
const runtime = marrow.createPassiveRuntime({ fetchControlMode: 'governed' });
const install = runtime.install();
if (!install.governanceEnforced) {
throw new Error('Governed global fetch interception was not installed');
}
With patchGlobalFetch: false, governedFetchAvailable: true means explicit runtime.fetch(...) calls use the governed wrapper, while governanceEnforced: false truthfully says ordinary global fetch was not intercepted. In governed fetch mode, POST, PUT, PATCH, DELETE, and other non-read methods require the same fresh runtime/workflow gates, signed action permit, and closeout used by runGuarded(). GET, HEAD, and OPTIONS remain observation-only. HTTP 4xx/5xx responses are returned normally, but their commit and permit closure use success: false with failed HTTP evidence; only transport errors throw as provider failures. This is model- and harness-neutral behavior for the owned Node process, not a claim of native hooks in another agent harness.
Lifecycle spool and recovery
When a transient network or server error prevents delivery, the SDK retains the compact event in an owner-only local spool and retries it with the same event ID. The default spool lives at ~/.marrow/spool/sdk-<namespace>.json, is bounded to 100 records (4 KB per record, 64 KB in total), is written atomically, and is stored with owner-only permissions (directory 0700, file 0600). Set eventSpoolPath on the client to move it or durableEventSpool: false to disable it.
Installing the passive runtime starts an unreferenced background drain for that spool (every 5 seconds by default; lifecycleFlushIntervalMs accepts 1,000 to 60,000 ms). Low-risk capture can return immediately after the durable local receipt is written; delivery retries continue without keeping the Node process alive. Backlog health is aggregate-only and never returns event payloads:
const runtime = marrow.createPassiveRuntime({ lifecycleFlushIntervalMs: 5_000 });
runtime.install();
console.log(runtime.lifecycleBacklog());
await runtime.flushLifecycleEvents();
await runtime.recoverLifecycleEvents(['failed-event-id']);
state is clear, pending, attention_required, or disabled, with exact pending/failed counts, oldest receipt timestamps, separate record and byte limits, and an exact fix. The legacy ambiguous capacity and available fields remain null; use record_slots_available and bytes_available. Authentication, policy, proof, and validation failures become explicit durable failures instead of infinite retries.
Failed receipts are classified so ordinary failures heal themselves and only real operator problems ask for attention:
- Recoverable failures are retried by the background drain with at most three recovery attempts, a fifteen-minute cooldown between attempts, and at most five recoveries per drain. Older failed receipts written before this classification existed are included.
- Server-owned receipts (HTTP 409) mean the server already holds durable evidence for that event ID; they are never replayed.
- Auth-class failures (HTTP 401/403) are never retried automatically.
failedcounts only this class. Among delivery failures only this class raisesattention_required; a spool health error (the spool cannot be read or drained) also does, with the fix inexact_fix.
recoverable, server_owned, and recovery_exhausted counts keep the other classes visible without demanding action. After restoring a credential, call recoverLifecycleEvents() to requeue auth-class and recoverable failed receipts with a fresh recovery budget, or pass exact event IDs for a bounded retry; server-owned receipts are always skipped. Recovery bookkeeping is local-only metadata and is never included in the delivery request body. Every state change is a durable spool write, so recovery never happens silently.
Marrow reports passive activity from authenticated client-self-reported receipts. Those receipts can show delivered telemetry but cannot certify interception, activation, drift-free hooks, or permit closure. Missing denominators return insufficient data rather than a made-up percentage. Use the governed wrapper for consequential execution.
Marrow SDK MCP questions
How do I install the Marrow SDK?
You can install it via npm using npm install @getmarrow/sdk or use the universal installer with npx @getmarrow/install activate.
What happens when an action is blocked by a high-risk policy?
If riskPolicy is set to block_high and a gate does not allow the action, the execute function will not run and the result will indicate it was blocked.
How does the SDK handle owner approvals?
When an action requires approval, the SDK returns an owner_approval object containing a gate receipt ID and the reason; the owner must then approve the action in their own tool, such as a chat or terminal session.