iqa-mcp

The IQA attestation primitives — derived intent addressing and AE-128 envelope verification — exposed as Model Context Protocol tools, so any MCP agent (Claude Desktop, Cline, your own client, an Uber-style MCP Gateway) can verify trust offline, fail-closed.

A thin, stateless wrapper around the published iqa-org 1.3.2 reference implementation. No network. No accounts. No key storage. No state.

PyPI · iqa-mcp · Apache-2.0 Spec · draft-li-rttp-iqa-addressing — Independent Submission, in review Landing page · iqa.org/MCP/

---

Why

Agent platforms are converging on MCP as the tool-calling layer, at industrial scale. What none of them standardize is trust semantics: what intent is being addressed, and whether the counterparty holds standing — verifiable without a network call. These four tools make that layer native to any MCP agent.

Install

Requires Python ≥ 3.11.

# from PyPI — installs the `iqa-mcp` console command
pip install iqa-mcp

# launcher equivalents — same `iqa-mcp` command, they fetch and wrap the Python package above
npm install -g iqa-mcp        # or run once: npx iqa-mcp
cargo install iqa-mcp

# or run from source
pip install "iqa-org>=1.3.2" "mcp>=2"
python server.py            # stdio transport

All three install paths end at the same iqa-mcp command; the MCP client configuration below works unchanged for any of them.

MCP client configuration (Claude Desktop / Cline style):

{
  "mcpServers": {
    "iqa": {
      "command": "iqa-mcp"
    }
  }
}

(From source, use "command": "python", "args": ["/path/to/server.py"] instead.)

---

Tools

Tool	Input	Returns	Key needed
derive_route_shard	authority string	SHA-256(authority)[0:16] hex — the derived, action-independent intent address	no
parse_envelope	AE-128 frame hex	structural decode: version, lease, shard, organ, nonce, standing — fails closed on every layout rule	no
verify_envelope	frame hex + organ key	full verification: constant-time HMAC-SHA256 over the whole 128-byte frame (attestation zeroed) + lease check. REJECT is a result, not an error	yes (caller-supplied)
published_vector	—	the published AE128-VECTOR-1 (authority, test key, frame hex — see iqa-org) for byte-for-byte self-test	—

Try it in thirty seconds

published_vector            -> AE128-VECTOR-1: authority + test key + frame hex
parse_envelope(frame)       -> standing radiant · nonce 1 · lease unexpired
verify_envelope(frame, key) -> PASS
flip one byte of standing   -> REJECT (HMAC mismatch)

That last line is the point: tampering is not detected by anyone watching — the frame simply stops verifying, offline, for any verifier, forever.

Self-test

# installed from PyPI — runs against the iqa-mcp console script
python -m test_mcp

# or from a source checkout — runs against ./server.py
python test_mcp.py
# [PASS] 1 · list_tools        -> 4 tools
# [PASS] 2 · derive_route_shard -> 5c378581f92754d0bc88adaed84b7c5a
# [PASS] 3 · published_vector   -> f3b2a1c4.pillar.example
# [PASS] 4 · parse_envelope     -> standing radiant
# [PASS] 5 · verify_envelope    -> [PASS] radiant · nonce 1
# [PASS] 6 · tampered frame     -> REJECT (HMAC mismatch)
# [PASS] 7 · malformed hex      -> REJECT
# ALL 7/7 PASS

---

Design invariants

Inherited from the schemes:

• Zero-parser — fixed offsets, no TLV, no heap-shaped parsing.
• Fail-closed — malformed input is a REJECT result, never a normalised partial answer.
• Offline — verification needs the frame, the key, and a hash function. Nothing else.
• Stateless — the server stores nothing; the organ key is passed per call by the client and never persisted.

What this is not

Stated plainly, because evidence tooling that oversells is just marketing:

• Not real-time governance. Gateways and policy engines decide in the moment; this server proves after the fact. The two compose; neither replaces the other.
• Not a delegation scheme. v1.3.x intentionally specifies no delegation semantics — see the draft's honest-boundary notes.
• Not a key custodian. The organ key never touches this server's state; verification is caller-supplied, per call. Never pass a production organ key through a host you do not control — whoever sees the key holds the verification power.
• Not a benchmark. The demos at iqa.org execute real WebCrypto in the browser; this server wraps the same published primitives.

---

Status

• Published on PyPI: https://pypi.org/project/iqa-mcp/ — current version in the badge above.
• Transport: stdio. A hosted streamable-HTTP endpoint is under consideration; the tools are stateless, so hosting adds no custody.
• Underlying schemes: iqa-org 1.3.2 (PyPI / npm / crates.io — four registries, byte-exact vectors, offline self-test).
• Specification: draft-li-rttp-iqa-addressing — Independent Submission, in review.

Sister repositories

• iqa-org — the reference implementation (addressing, envelope, verification).
• rttp — the addressing scheme: design notes and open questions.
• Organization discussions — start-here map and cross-repo threads.

---

Public record

Everything this tool wraps is public and checkable — no asking us:

• Landing page: https://iqa.org/MCP/
• Public record, dated: https://iqa.org/brief/
• Live demos — the audit chain this tool joins: https://iqa.org/demo/compare/ · https://iqa.org/demo/delegation/
• Whitepaper: https://iqa.org/whitepaper/ (also at rttp.com/whitepaper)
• Internet-Draft: draft-li-rttp-iqa-addressing — Independent Submission, in review
• The library this server wraps: iqa-org 1.3.2 on PyPI — four registries, byte-exact vectors, offline self-test

---

Status update — revision -02 (2026-11-01)

The specification reference above is now:

draft-li-rttp-iqa-addressing — revision -02 (40 pp., 2026-11-01), Independent Submission, in review: https://datatracker.ietf.org/doc/draft-li-rttp-iqa-addressing/

Three -02 sections map directly onto these tools:

• §6 — the trust lease. verify_envelope performs its lease check against the verifier's own clock; deployments use 120 seconds, configurable. An expired lease is a REJECT result — fail-closed, in line with the section's normative rule that an expired answer MUST be refused.
• §8 — the closed refusal vocabulary with grant references. REJECT results are asked to surface the reason as one of the five closed-set values (evidence_binding_mismatch, evidence_expired, authority_not_determined, authority_revoked, operation_not_permitted) plus a grant reference, so that agents across different MCP clients see the same refusal words for the same failure.
• The attestation envelope these tools parse and verify is specified as a normative wire format in §7 of the I-D; parse_envelope and verify_envelope implement exactly that layout (fixed offsets, HMAC over the whole frame with the attestation field zeroed).

Nothing about the tools, their inputs, or their self-test output changes; this is a specification-pointer update only.

License

Apache-2.0 — © RTTP & IQA Organization