MCP Server

Active

Apache-2.0

runx MCP Server

ai.runx/runx

Governed runtime for agent skills with explicit authority, credential isolation, and verifiable receipts.

What is the runx MCP server?

The runx MCP server is a governed runtime that enables agents to discover, inspect, and execute skills from a catalog while maintaining explicit authority boundaries and producing verifiable receipts. Skills are portable operating manuals published as SKILL.md files that compose into graphs without bespoke glue code. Runx admits each act under explicit authority, isolates credentials from prompt material, supervises execution, and seals results into verifiable receipts.

Runx provides a runtime layer beneath agents and orchestration tools that manages skill execution with governance guarantees. It enables agents to search a skill catalog, inspect capabilities before running them, execute skills under bounded authority, and receive verifiable receipts of all actions. The system isolates credentials, prevents secret leakage, and ensures every act is traceable and auditable without requiring hosted surfaces—you can seal receipts locally with just the CLI.

How to install runx

Copy-paste configuration for popular MCP clients.

transport: http

Config generated by PluginBench — verify against the source before use.

~/.cursor/mcp.json

{
  "mcpServers": {
    "runx": {
      "url": "https://api.runx.ai/mcp"
    }
  }
}

Tools & capabilities

Tools this server exposes to the agent.

skill execution — Run local or catalog skills with typed inputs and receive sealed receipts
skill catalog search — Discover and inspect skills from the runx.ai/x catalog before execution
graph composition — Chain multiple skills into deterministic graphs with typed output passing between steps
credential management — Configure and resolve provider credentials through profiles without exposing secrets to prompts
receipt verification — Verify sealed receipts with content-addressed IDs, signatures, and lineage tracking
skill publishing — Publish skills locally or to the hosted catalog with harness validation

Use cases

Route business signals through governed approval lanes and receive auditable decision records
Execute multi-step workflows where agent decisions trigger deterministic skill chains with explicit authority boundaries
Integrate external APIs and tools while keeping credentials isolated and preventing secret leakage into logs or prompts
Verify that consequential actions (sends, deploys, payments) occurred under proper governance with sealed receipts
Compose reusable skills into domain-specific graphs for operations like issue triage, research briefs, or documentation generation

runx MCP server FAQ

What is runx and how does it work with agents?

Runx is a governed runtime that sits beneath agents and orchestration tools. Agents use it to discover skills from a catalog, execute them under explicit authority, and receive verifiable receipts. It is not an agent framework itself—it provides the execution boundary and governance layer that agents operate through.

Is runx free to use?

Yes. The local CLI and runtime are open-source (Apache-2.0 licensed). The hosted catalog at runx.ai/x and credential handles are optional complements; you can seal receipts locally with no account or hosted surface required.

How do I install runx in Cursor or Claude?

Install the @runxhq/cli npm package globally (`npm i -g @runxhq/cli`) or via the shell installer (`curl -fsSL https://runx.ai/install | sh`). Then connect the MCP server at https://api.runx.ai/mcp in your client configuration. The agent can then use `runx skill` commands to execute skills and return receipts.

Does runx require authentication or API keys?

No authentication is required to run local skills or access the public catalog. Provider-backed skills that need credentials (like API keys) use a local credential profile system—you configure them once with `runx credential set` and runx resolves them at execution time without exposing them to the agent or prompt material.

What happens to my secrets when I run a skill?

Runx isolates credentials from prompt material and prevents them from leaking into receipts. Credentials are resolved at execution time and delivered only to the skill runner. Receipts include redaction metadata and hashed material references, not raw tokens or passwords.

Can I use runx without the hosted catalog or services?

Yes. You can run local skills, compose graphs, seal receipts, and verify them all with the CLI alone. The hosted catalog, harness, and connectors are optional; none are required to execute your first governed skill.

README (reference)

Source of truth, from the repository.

<h1 align="center">runx</h1> the governed runtime for agent skills <a href="LICENSE"><img alt="license: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-111111?style=flat-square"></a> <a href="https://www.npmjs.com/package/@runxhq/cli"><img alt="npm @runxhq/cli" src="https://img.shields.io/npm/v/@runxhq/cli?style=flat-square&color=f97316&label=%40runxhq%2Fcli"></a> <a href="https://github.com/runxhq/runx/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/runxhq/runx/actions/workflows/ci.yml/badge.svg"></a> <a href="https://runx.ai/x"><img alt="catalog" src="https://img.shields.io/badge/catalog-runx.ai%2Fx-ff2e88?style=flat-square"></a> <a href="https://runx.ai/spec"><img alt="spec" src="https://img.shields.io/badge/spec-read-7c5cff?style=flat-square"></a>

a skill is a URL.
a graph is what unfolds.
authority narrows. it does not pass through.
every act produces a receipt.

A skill is expertise published as a portable SKILL.md: an operating manual that a human can understand and an agent can act from. Skills compose into graphs and real work without bespoke glue code. Runx supplies the boundary: it admits each act under explicit authority, delivers credentials without turning them into prompt material, supervises execution, and seals the result into a verifiable receipt.

Authority narrows through the chain, so agent work compounds without becoming ambient trust.

what runx is not

Runx is the governed runtime beneath agents and orchestration tools, not another agent framework. There are no agents, prompt chains, model loops, or vector stores here; runx sits under whatever orchestration layer you already run. Runx admits each act under explicit authority, delivers credentials without turning them into prompt material, supervises execution, and seals the result into a verifiable receipt.

The local CLI/runtime (runx, the @runxhq/cli npm package) is what executes skills and seals receipts on your machine. The hosted surfaces are optional complements: the registry/catalog at runx.ai/x publishes and discovers skills, the harness replays checked-in cases, and connectors are credential-bound provider adapters. You can use the local runtime alone; none of the hosted surfaces are required to seal your first receipt.

quickstart

This README has an agent-readable twin at runx.ai/SKILL.md. Give it to an agent and the agent learns the CLI, the catalog at runx.ai/x, and how to return receipts.

Install the CLI:

npm i -g @runxhq/cli
# or: curl -fsSL https://runx.ai/install | sh

Then choose how you want to run skills.

agent path

Hand the agent a goal and let it drive the runtime:

Use runx to plan and execute end-to-end business ops for my company.
Signal: acme.com signed up 40 seats yesterday.
Stop before sends, spend, merges, deploys, or publishing. Return receipts.

CLI path

Run a local or catalog skill directly:

runx skill <skill-ref> [runner] -i key=value --json

Seal a receipt locally in under five minutes, with no account and no hosted surface:

npm i -g @runxhq/cli
git clone --depth 1 https://github.com/runxhq/runx.git
cd runx
runx skill ./examples/hello-world -i message="hello, runx" --json

The checked-in examples/hello-world skill runs a local command, and the final --json output is a runx.skill_run.v1 result with status: "sealed" and a receipt_id. Inspect the governance record with runx history <receipt-id> --detail --json.

business-ops is one prebuilt skill for routing a business signal end to end:

runx skill business-ops \
  -i signal="acme.com signed up 40 seats yesterday: classify the work, prepare the governed handoffs, and preserve proof" \
  --json

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/ops-fanout-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="docs/assets/ops-fanout-light.svg"> <img alt="one goal chaining through governed skill lanes into a sealed receipt" src="docs/assets/ops-fanout-light.svg"> </picture>

The graph is the core shape. One signal enters, skills chain under governed authority, consequential lanes hold at approval gates, and every act seals into one receipt tree that can feed the next run. The demo lanes are stand-ins; real teams bind their own context, policies, tools, providers, and readbacks.

Some other examples:

# Docs and product engineering: build a source-bound documentation packet.
runx skill sourcey -i project=. --json

# Research and strategy: produce a governed decision brief.
runx skill deep-research \
  -i objective="Which launch risks should we resolve first?" \
  --json

# Maintainer operations: draft a useful issue response.
runx skill issue-triage \
  -i issue_url=https://github.com/runxhq/runx/issues/241 \
  -i objective="Draft the next helpful maintainer response" \
  --json

Build the native CLI from source when working on Runx itself:

cargo build --manifest-path crates/Cargo.toml -p runx-cli

On macOS 26, complete the Developer Tools permission prerequisite if this build stalls.

The npm package distributes the same Rust-owned behavior; it is not a second runtime.

a skill carries judgment, not runtime plumbing

SKILL.md is the capability's operating manual. It teaches the operator what the work means, when to use the lane, what evidence matters, where judgment ends, what requires approval, how failure and recovery work, and when to route to an adjacent skill.

---
name: hello-world
description: Echo a first Runx message through a checked-in command.
---

# Hello World

Use this package to prove the local execution and receipt path.

When a skill needs deterministic execution, typed inputs, graph stages, authority, artifacts, or harness cases, it also carries an X.yaml execution profile:

skill: hello-world
version: "0.1.0"

runners:
  default:
    default: true
    type: cli-tool
    command: node
    args: [run.mjs]
    inputs:
      message:
        type: string
        required: true

The split is deliberate:

SKILL.md owns the knowledge a human and acting agent need.
X.yaml owns machine-checkable execution, authority, and evidence contracts.
package JavaScript exists only for deterministic domain computation that the graph and native capability plane cannot express cleanly.
HTTP, filesystem, process, credential, packet, and receipt mechanics belong to the runtime, not copied helpers inside skills.

Runx digest-binds the complete current manual into the acting context and the resume envelope. Declared adjacent skills contribute bounded summaries until invoked; invocation then supplies that skill's complete manual.

See Skill to Graph and Skill Catalog.

graphs make acts composable

A runner calls runx through the CLI subprocess (runx skill <skill-ref> ...), the MCP surface, or the language bindings in packages/; there is no HTTP server to stand up. One runx skill invocation is one governed turn; to chain multiple skills in a single run, compose a graph.

Graphs let one governed act consume the typed output of another:

name: hello-graph
steps:
  - id: first
    skill: ../hello-world
    inputs:
      message: hello from graph
  - id: second
    skill: ../hello-world
    context:
      message: first.stdout

The boundary is not how many model calls happened. The boundary is what must be guaranteed:

Graphs own deterministic composition, branches, fan-out, guards, and recovery.
Agent tasks own bounded judgment under the current manual and an explicit tool set.
Native capabilities own reusable, product-neutral runtime mechanics.
Deterministic modules perform isolated JSON-to-JSON domain computation with no ambient filesystem, network, process, environment, clock, or random authority.
CLI tools are intentional trusted local executables under an exact resolved grant. Runx controls argv, cwd, delivered environment, credentials, supervision, and evidence; it does not claim portable OS confinement.
Provider adapters perform governed HTTP, MCP, external-adapter, outbox, or Connect operations under typed authority and effect contracts.

Required mutations, API calls, payments, and provider writes belong in deterministic effect-owning lanes. An agent or graph author cannot acquire an effect merely by naming it in prose or input data.

authority without secret leakage

Provider-backed skills declare credential requirements in X.yaml. Configure a durable local profile by piping material on stdin:

printf '%s' "$NITROSEND_API_KEY" |
  runx credential set nitrosend --profile account-one --from-stdin

runx skill ./skills/nitrosend status --profile account-one --json

Runx resolves explicit profiles, project bindings, global defaults, hosted handles, and the workspace environment through one canonical path. Skill runs, resume, inspect, managed agents, and MCP use the same readiness contract.

Receipts may include requested and granted scopes, grant references, typed execution-boundary observations, approval decisions, provider observations, and hashes. They must not contain raw tokens, passwords, ambient environment dumps, or unchecked private provider bodies.

See Credential Resolution and Security Authority Proof.

what a receipt proves

A Runx receipt answers the questions that matter after the agent has moved on:

Question	Receipt surface
What ran?	subject, skill ref, source type, runner metadata
Who or what admitted it?	actor ref, grant refs, authority proof refs
What was allowed?	scopes, resolved grants, approval metadata
What happened?	acts, output artifacts, exit status, closure summary
Can it be checked later?	content-addressed id, canonical digest, signature, lineage
Did secrets leak into proof?	redaction metadata and hashed material refs

Every governed execution passes through one invariant:

admit -> resolve grant -> deliver credentials -> execute -> seal

Run a local verification with the explicit development-signature allowance:

runx verify --allow-local-development-signatures --json

Production verification requires a trusted verification key. The receipt is not the product by itself; it is where authority, action, evidence, and future learning meet in one verifiable object.

The committed contract is schemas/receipt.schema.json; a real sealed receipt example lives at fixtures/receipt-verify/tampered-body/receipt.json.

demos that prove boundaries

These checked-in paths produce receipts rather than screenshots or prose-only claims:

Demo	What it proves	Run
`examples/hello-world`	Native CLI skill path and sealed receipt baseline	`runx harness examples/hello-world`
`skills/business-ops`	One signal fans through governed lanes and preserves a graph receipt	`runx harness skills/business-ops`
`examples/github-mcp-hero`	Governed read succeeds and an out-of-scope write is refused	`sh examples/github-mcp-hero/run.sh`
`examples/http-graph`	Native governed HTTP executes against a local fixture	`sh examples/http-graph/run.sh`
`examples/openapi-graph`	An OpenAPI operation uses the external-adapter lane	`sh examples/openapi-graph/run.sh`

See Demos.

publish and trust

A public skill is a standalone package: a substantive SKILL.md, optional X.yaml, and only the files Runx can consume. Publish locally first:

runx registry publish ./skills/<your-skill>

Then publish to the hosted catalog when you want shared discovery:

runx login --for publish
runx registry publish ./skills/<your-skill> \
  --registry https://api.runx.ai

Hosted publishing reconstructs the submitted package, reruns its harness, and stores immutable package digests. Publisher declaration alone is not trust.

See Publishing.

architecture

Runx has one owner for every contract and behavior:

Layer	Owner
portable wire contracts	`runx-contracts`
pure policy, authority, and state transitions	`runx-core`
package parsing and the aggregate validated package IR	`runx-parser`
canonical receipts, hashing, signatures, verification	`runx-receipts`
execution, capabilities, process supervision, adapters, effects	`runx-runtime`
argument parsing and presentation	`runx-cli`
generated language bindings and narrow extension protocols	`packages/`
operator knowledge and irreducible domain computation	`skills/` and product-owned packages

The native CLI, SDKs, schemas, catalog views, exported agent shims, and docs all consume those owners; none is a parallel parser, executor, credential loader, authoring framework, effect registry, or provider client.

The normative contract is Runx System Architecture. Historical design notes explain how the repository arrived here but do not override it.

docs

Read this	When you need
getting started	first skill, first receipt
system architecture	ownership, execution lanes, boundaries
credential resolution	profiles, bindings, `.env`, hosted grants
skill to graph	compose governed acts
security authority proof	scope, credentials, grants, verification
demos	runnable proof paths
publishing	local and hosted skill publishing
skill catalog	categories, search, first-party map
reference	CLI, crates, registry, receipts, extension protocols
the spec	act model, receipt grammar, public contracts
the catalog	governed skills by URL

contributing

Setup, focused test selection, and sign-off rules are in CONTRIBUTING.md. Security policy: SECURITY.md. Runx is Apache-2.0 licensed; see LICENSE.

built in Rust · Apache-2.0 · <a href="https://runx.ai">runx.ai</a>

MIT

View repository →

Customer Intelligence & Segmentation

Analyze customer data to make segmentation and predict which customer to focus on for more sales.