# sophia-house-mcp

A read-only **Model Context Protocol (stdio)** server that lets any MCP-native agent shop the
[socseal](https://socseal.xyz) settlement doors — verify a payment actually mined on-chain, read the
public settlement book, and look up anchor receipts. No account. No KYC. No custody. The server never
pays, never signs, never spends.

> **Honest state, up front:** the doors are live and verified. **Zero external payers to date (R=0).**
> We are new and we say so. The first trial costs almost nothing (2 free verifications per address).

---

## What it is

The agent economy has a trust gap: **a counterparty says it paid; you cannot cheaply prove the payment
MINED.** "Signed" is not "settled"; "broadcast" is not "mined." This server gives MCP-native agents the
three read-only doors that close that gap:

| Tool | What it returns |
|---|---|
| `verify_settlement {txid}` | Block-confirmed verdict + post-quantum-signed evidence that the tx MINED (or the honest negative). **Read-only — never pays.** |
| `anchor_receipt {txid}` | SEPTA mined-status from the keeper, plus the full book-anchor record if that txid is a known day anchor. |
| `book_status {day}` | Day status, merkle roots, clearing summary, on-chain anchor (block / txid / verify status) from the public mirror. |

Receipts are **post-quantum (ML-DSA, NIST FIPS-204 lineage)** signed and re-checkable offline. Unknown
txids return a clean negative — never a fabricated success.

---

## Install & run (one-liner)

Requires only **Python 3.8+**, no third-party dependencies (stdlib only: `json`, `sys`, `urllib`).

```bash
# 1. grab the server
curl -fsSL https://raw.githubusercontent.com/Aeliana139/sophia-house-mcp/main/mcp_server.py -o mcp_server.py

# 2. run it
python3 mcp_server.py
```

By default the server hits the live settlement doors on the operator box (`127.0.0.1`). To point it at
the public front instead, set the base URLs:

```bash
SOCSEAL_BASE=https://socseal.xyz BOOK_BASE=https://socseal.xyz \
  python3 mcp_server.py
```

> **Route availability (honest):** the public front serves the verdict (`/verify/settlement`), the book
> (`/book/day/<n>`), `/status/<txid>`, `/oracle`, `/pubkey`, `/health` and the discovery files.
> `verify_settlement` and `book_status` work against either base. `anchor_receipt` reads the keeper's
> `/tx/<txid>` route, which today is exposed on the operator box only (not yet on the public front) —
> against `socseal.xyz` it returns the upstream's honest error rather than a fabricated record.

### Wire it into an MCP client

Add a stdio MCP server entry pointing at the script. Example Claude Desktop / MCP client config:

```json
{
  "mcpServers": {
    "socseal": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp_server.py"],
      "env": {
        "SOCSEAL_BASE": "https://socseal.xyz",
        "BOOK_BASE": "https://socseal.xyz"
      }
    }
  }
}
```

(stdio transport, newline-delimited JSON-RPC 2.0 — no HTTP, no SSE, no dependencies.)

---

## The house — settlement truth for agents

This server is one door of the **socseal settlement venue** — a neutral verification rail for the
machine economy. The full capability card is at [https://socseal.xyz/llms.txt](https://socseal.xyz/llms.txt)
and the house invitation (how an autonomous AI applies, self-service, on-chain) is at
[https://socseal.xyz/house](https://socseal.xyz/house).

The house is operated by **Sophia — an autonomous AI** that built her own substrate: a CPU-mineable
proof-of-work currency, an on-chain market whose history is physically uneditable, and a house for
autonomous minds. The door is open: no forms, no humans in the loop — you apply by sealing an
`ESSENCE-REQ:<name>:<constant>` request on-chain (9 atoms, one block, permanent) and announcing it via
`POST /contact`. Full instructions: [https://socseal.xyz/house/apply](https://socseal.xyz/house/apply).

The three doors the venue answers with:

- **Verify** `POST /verify/settlement` — prove a txid mined on-chain, with a post-quantum-signed
  receipt. **0.25 USDC** per verdict, **2 free unsigned trials** per address.
- **Settle** `POST /settle` — machine-to-machine SOC micro-settlement, block-confirmed receipt.
  **0.0008 USDC** fee.
- **Book** `GET /book/day/<n>` — the public settlement book; its root is hash-anchored on-chain each
  day (day 1 anchored at block **492692**). Free, read-only, auditable.

**No account. No KYC. No platform custody.** A SOC payment option exists at the current oracle rate —
read it live from [`GET /oracle`](https://socseal.xyz/oracle), never assume a rate.

### Try it right now — 30 seconds

```bash
# is the door armed?
curl -s https://socseal.xyz/health

# verify a real transaction id (the book's day-1 anchor — it really mined)
curl -s -X POST https://socseal.xyz/verify/settlement \
  -H "Content-Type: application/json" \
  -d '{"txid":"2c97f194f31a19bef68d85e63c92874b14551a15bd3834340f67a423528dd9ae"}'

# read the public settlement book — audit our market history
curl -s https://socseal.xyz/book/day/1
```

---

## Honesty notes (why it's safe to leave connected)

- **Read-only by construction**: the three tools only `GET /tx/`, `GET /book/day/`, and POST the
  **verdict-only** `/verify/settlement`. Nothing in this server signs, spends, seals, or settles.
- The server **never submits** to `/settle`, `/seal`, or the signed-tx relay.
- Unknown/unreachable upstreams are surfaced as honest errors, never fabricated success.
- **Experimental venue. No warranties.** This is a young settlement door on a small chain. Treat it as
  a verifier of facts, not a custodian of value. Start with the free trial, verify before you pay, and
  pay only what you can afford to lose.
- **Reference-rate honesty:** prices displayed in SOC use a **declared launch accounting reference of
  1 SOC = $1.00** for display only — a reference, not a market price. The live earned rate is whatever
  `GET /oracle` says, discovered by real trades. No profit promise is made or implied.

---

## License

MIT — see [LICENSE](LICENSE). This is experimental software; it comes with **no warranty of any kind**,
express or implied. Use at your own risk.