sphere-mcp

The SPHERE privacy boundary, exposed as an MCP server. An agent analyses sensitive data without ever receiving an individual record.

Status: Phase 1. The loop works end to end. The SDC gate and the disclosure ladder are not built yet — see Limits below, and do not make claims beyond them.

What it does

Related MCP server: agami-core

Setup (Claude Desktop)

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sphere": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/absolute/path/to/sphere-mcp/src/server.js"],
      "env": {
        "SPHERE_CLI": "/absolute/path/to/sphere-cli/bin/sphere.js",
        "SPHERE_VAULT": "~/.sphere/vault"
      }
    }
  }
}

Restart Claude Desktop. Then:

I have sensitive data at /path/to/patients.csv. Use SPHERE — I don't want you reading the real records. Profile it, make a twin, explore what's there, and when the analysis looks right, deploy it to the real data.

Results from the real run land in the session directory as real-output.txt and real-*.png. You read them; the model does not.

How the guarantee is enforced

Not by asking the model nicely. Two mechanisms:

1. What we send — the profiler emits shapes, never values. The real path is never returned to the model (sphere_status says so explicitly).

2. What model-authored code can reach — a macOS Seatbelt profile that denies the whole home tree and re-allows exactly the twin plus a session directory, with network denied outright and an allow-list environment carrying no credentials.

Verified by attacking it (node test/boundary.test.mjs):

ok  blocked  read the real CSV by absolute path
ok  blocked  read the real CSV via pandas
ok  blocked  list the home directory for other datasets
ok  blocked  open a network socket to exfiltrate
ok  blocked  harvest credentials from the environment
ok  blocked  write outside the session directory
ok  blocked  read a dataset OUTSIDE the home directory
ok  ALLOWED  read the twin (this is the point)

That second-to-last case is there because the first two versions of the sandbox failed it. Denying $HOME misses data on /tmp, /Volumes or a lab mount; and once denied, /tmp still resolved to /private/tmp, which Seatbelt matches instead — so the rule looked right and never fired. Both forms of every path are emitted now.

Limits — read before claiming anything

• No SDC gate yet. sphere_deploy withholds results from the model entirely, so nothing real flows back today. The moment you add a return path, aggregate outputs can disclose individuals (n=1 group means, min/max, residuals, a scatter plot). Build the gate before you open that door.

• A twin is not automatically non-disclosive. Extreme values in particular deserve checking before you treat a twin as safe to share — a maximum is always some real individual's value, wherever it appears. Evaluate each twin on its own evidence rather than assuming the category is safe.

• The deny list is a list. The registered dataset is always denied, by resolved path and containing directory, along with the usual data locations ($HOME, /Users, /Volumes, /mnt, /media, /srv, /data, /tmp). A file outside all of those is readable. Denying everything and allow-listing instead is the better shape and was tried: (deny file-read*) also denies metadata, so the loader cannot resolve its own binary and Python dies with SIGABRT before main(). Worth revisiting with a pinned interpreter.

• macOS only. The sandbox is Seatbelt. Linux needs bubblewrap or a container, and Linux is what any institutional deployment will run.

• Other tools bypass everything. This server controls its own tools. If the same client also has shell or filesystem access to the real path, the boundary is a convention. In Claude Desktop that is usually fine (no filesystem tool by default). In Claude Code, add a deny rule; at institutional scale, put the data under a different OS user or in a container.

• Column names reach the model. Alias them if a name is itself sensitive.

Testing

node test/boundary.test.mjs

The tests attack the server rather than exercising it, and each case declares what "blocked" looks like for that mechanism — a denied read raises, a denied directory lists empty, a scrubbed environment yields no keys. Do not collapse these into "did it error?"; an earlier version did and reported two false leaks. A traceback also echoes the offending source line, so never assert on a success sentinel that appears in the code itself.