@aithos/mcp-remote

The "agent at the client" shape (M3). Run a delegated Aithos MCP server on ANY machine — Claude Desktop, Claude Code, Cursor — with no local keystore and no subject keys. Reads hit the Aithos platform primitives; writes are composed client-side and published as ONE delegate-signed edition (aithos.publish_ethos_edition, spec §11). Authority comes from a mandate pack: one JSON file the subject hands to the agent host.

Quickstart (Claude Desktop)

1. The subject mints a mandate + delegate key and exports the pack (aithos grant … --pack on their machine):

{
  "aithos-mandate-pack": "1",
  "mandate":   { "...": "the signed mandate (§4)" },
  "agent_key": { "seed_hex": "…", "pubkey_multibase": "z…" },
  "endpoints": { "api": "https://api.aithos.be" }
}

2. The agent host adds ONE entry to claude_desktop_config.json:

{
  "mcpServers": {
    "aithos": {
      "command": "npx",
      "args": ["-y", "@aithos/mcp-remote", "--mandate-pack", "/abs/path/agent-pack.json"]
    }
  }
}

3. That's the whole setup. The session is scope-filtered (tools/list shows exactly what the mandate allows — ask mandate_describe), writes STAGE until ethos_commit (one edition per coherent change), and the mandate's validity window + revocation are re-checked before anything persists. Revoking the mandate on the subject's side kills the agent's write authority immediately.

Claude Code: claude mcp add aithos -- npx -y @aithos/mcp-remote --mandate-pack /abs/path/agent-pack.json · Cursor: same command/args in mcp.json.

What the agent can do

Exactly what the canonical catalogue (@aithos/agent-tools) exposes for the mandate's scopes: read/list/search sections, assemble budgeted context packs, diff since a known edition, stage + commit edits in its actor sphere, introspect its own authority (mandate_describe, ethos_preflight_write). Nothing else is listed, and forced calls refuse at dispatch (defense in depth).

Library use

import { RemoteStorage } from "@aithos/mcp-remote";
import { createServer } from "@aithos/mcp";

const storage = new RemoteStorage({
  transport: { baseUrl: "https://api.aithos.be" },
  writeAuthority: { kind: "delegate", granteeId, seed, pubkeyMultibase, mandate },
});
const server = createServer({ storage, mandate: { scopes, document: mandate }, delegate });

RemoteStorage implements AithosStorage end-to-end: platform reads (manifest, per-section index + bodies, editions at a height → ethos_diff_since works here), delegate-signed transactional writes (applyEdits, decision D5: protocol-client's publish pipeline, no §11 reimplementation), revocation lookups (-32020 → null).