ATLAS MCP

Safe execution · Durable memory · Verified outcomes

An open-source Model Context Protocol runtime for files, terminal, browser, memory, and computer use — with policy checks, bounded execution, and cryptographic evidence for every result.

Contents

Related MCP server: Container-MCP

Why ATLAS MCP

Most MCP servers hand a model a tool and hope for the best. A command runs, a click lands, a file is written — and "it returned without an error" is treated as success.

ATLAS MCP separates the action succeeded from the goal was achieved.

• Tool call executes immediately

• Success = no exception thrown

• Policy, if any, checked once

• Mutations are indistinguishable from reads

• Output is trusted

• No durable record

• Plan and execute are separate tool calls

• Success = declared evidence predicates passed

• Policy re-evaluated at execution time

• Mutations need evidence and an exact approval phrase

• Page content is explicitly marked untrusted

• Redacted receipt + SHA-256 execution certificate

If a mutation succeeds but its required evidence is missing or false, the task is partial — never verified_success.

One runtime, five execution layers 🧭

ATLAS MCP turns a tool call into a durable, inspectable task:

Every layer passes through the same policy, approval, budget, verification, receipt, and certificate pipeline.

Where you can use ATLAS MCP 🛠️

ATLAS MCP works with any MCP client that can launch a local stdio server.

What people actually do with it

A coding client submits one bounded operation with the evidence it expects:

{
  "goal": "Run the repository checks",
  "operation": {
    "kind": "terminal",
    "action": "run",
    "command": "pnpm",
    "args": ["check"]
  },
  "requiredEvidence": [
    { "type": "exit_code", "value": 0 }
  ]
}

The task reaches verified_success only if the process exits 0. A process that runs and exits 1 is a completed action with failed evidence — reported as partial.

pnpm atlas run --request examples/07-project-decision-memory/task.json

Records are scoped, provenance-tagged, and pass through secret redaction before they are persisted.

See all runnable examples — browser inspection, verified file writes, terminal checks, scoped memory, and computer capability discovery.

Quickstart 🚀

Requirements: Node.js 22+, pnpm 9.5, and optionally Chrome, Chromium, or Edge for browser work.

git clone https://github.com/XAGI-Lab/atlas-mcp.git
cd atlas-mcp
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm atlas doctor
pnpm atlas init --client generic

Mutations pause for an exact, expiring, task-scoped approval phrase. See installation and client setup for Claude Desktop, Cursor, VS Code, generic clients, Python, and Docker.

A deliberately small MCP surface ✨

Six tools, in front of five capability runtimes:

High-level tools keep schemas compact while the operation contract carries the specific file, terminal, browser, memory, computer, or system action.

How execution works ⚙️

flowchart LR
    Client["MCP client"] --> Plan["Persist bounded plan"]
    Plan --> Policy{"Policy at plan time"}
    Policy -->|deny| Stop["Policy blocked"]
    Policy -->|allow or exact approval| Recheck{"Policy at execution time"}
    Recheck --> Runtime["File · terminal · browser · memory · computer"]
    Runtime --> Observe["Post-action observation"]
    Observe --> Verify{"Evidence predicates pass?"}
    Verify -->|yes| Success["Verified success"]
    Verify -->|no| Partial["Partial or failed"]
    Success --> Receipt["Redacted receipt + SHA-256 certificate"]
    Partial --> Receipt

Task lifecycle:

planned → awaiting_approval → running → verifying
                                     ↘ verified_success
                                     ↘ partial | failed | cancelled | budget_exhausted

Policy is evaluated twice — once when the plan is persisted and again at execution — so a stale plan can never ride a since-tightened policy.

Evidence, not leaderboard theatre 📊

The numbers below come from committed scripts and JSON artifacts measured on an Apple Silicon Mac. They are component measurements, not a claim that ATLAS MCP is universally "the best" or that unlike benchmarks are comparable.

Read the research index, the benchmark methodology, and the raw microbenchmark and LoCoMo artifacts.

Browser-agent evaluation — harness registered, score not yet claimed

The repository contains a pre-registered browser-agent evaluation harness:

Task IDs, upstream revisions, and dataset hashes are frozen in benchmarks/browser-agent/manifests/ and enforced by pnpm benchmark:browser:verify-upstream. A score will be published only after a full fixed-denominator run completes without infrastructure-invalid pairs and its sanitized artifact passes the publication gate.

Safe defaults 🔒

See the threat model and security policy for residual risks.

Reproduce the scores 🧪

# full validation gate
pnpm check
pnpm evals
pnpm e2e
pnpm pack:check
pnpm security:audit

# local memory, browser, terminal, and computer microbenchmarks
pnpm benchmark:core

git clone https://github.com/snap-research/locomo.git /tmp/locomo
pnpm benchmark:locomo -- \
  --dataset /tmp/locomo/data/locomo10.json \
  --output docs/research/results/locomo-retrieval.json

Contract and registered-selection checks run with no model and no network environment:

pnpm benchmark:browser:check
pnpm benchmark:browser:verify-upstream

The MiniWoB development suite additionally needs the pinned MiniWoB++ assets, a built CLI (pnpm build), and an agent configuration whose api_key_env names a variable present in the environment:

uv run --project benchmarks/browser-agent --extra miniwob \
  atlas-browser-bench run-miniwob \
  --manifest benchmarks/browser-agent/manifests/miniwob-125-v1.json \
  --run-dir benchmarks/browser-agent/runs/miniwob-candidate \
  --workspace benchmarks/browser-agent/runs/workspaces \
  --base-url "$MINIWOB_BASE_URL" \
  --browser-executable "$ATLAS_MCP_BROWSER" \
  --implementation-commit "$(git rev-parse HEAD)" \
  --agent-config benchmarks/browser-agent/runs/config/agent.json

Run outputs — HAR, screenshots, video, and transcripts — are Git-ignored and must never be committed.

Benchmark artifacts include dataset hashes, environment details, sample counts, latency percentiles, and explicit claim boundaries.

SDKs and implementation languages 🧩

ATLAS MCP is capability-driven, not language-restricted. Rust, Go, Python, TypeScript, Swift, C#, or another language can be used when measurement shows a real improvement in isolation, portability, performance, reliability, or platform integration without fragmenting the public contracts.

Repository map 🗂️

apps/cli/                   CLI and stdio entrypoint
packages/protocol/          strict task and operation schemas
packages/runtime-core/      lifecycle, budgets, retries, cancellation
packages/policy-core/       local policy and scoped approvals
packages/server/            six-tool MCP server and runtime router
packages/file-runtime/      confined filesystem operations
packages/terminal-runtime/  shell-free process supervision
packages/browser-runtime/   isolated browser automation and stable-DOM wait
packages/computer-runtime/  governed local computer-use adapters
packages/memory/            scoped hybrid retrieval and lifecycle controls
packages/storage-sqlite/    durable local state
packages/verifier-core/     deterministic evidence predicates
packages/receipt-schema/    receipts and execution certificates
packages/sdk-ts/            TypeScript client SDK
sdk-py/                     Python client SDK
benchmarks/browser-agent/   pre-registered browser-agent evaluation harness
evals/                      deterministic evaluation harness
scripts/                    benchmark and release checks
docs/research/              methods, findings, and raw results
examples/                   runnable task examples

Documentation 📚

Contributing 🤝

Code, adapters, benchmark harnesses, verifier predicates, documentation, and threat analysis are all welcome.

1. Read CONTRIBUTING.md and the Code of Conduct.

2. Sign your commits under the DCO (git commit -s).

3. Run pnpm check before opening a pull request.

4. Report vulnerabilities through GitHub private vulnerability reporting — never in a public issue.

License 📄

Software and documentation are licensed under the Apache License 2.0. The official logo and hero artwork are licensed under CC BY-ND 4.0; see BRAND.md. Third-party benchmark datasets retain their own licenses and are not included in this repository.

Built in the open by XAGI Labs.

ATLAS MCP brand assets © XAGI Labs Private Limited, licensed CC BY-ND 4.0.