AMR

Install AMR

Written so that an AI agent (Claude Code, Cursor, any MCP client) can install AMR and reach a first verified mandate alone. No account, no email, nobody to ask.

1. Run the server

It needs uv. The PyPI package is named “mandatia” (version 0.1.2 on 16 November 2026).

uvx mandatia

# the latest code of the repository instead:
uvx --from git+https://github.com/JC7333/amr amr

# or clone and run:
git clone https://github.com/JC7333/amr.git && cd amr && uv sync && uv run amr

uvx amr installs a different, unrelated project: do not use it. AMR runs with version 1 and version 2 of the MCP Python SDK (mcp>=1.2,<3); no extra version pin is needed.

Everything runs on your machine. AMR makes no network call, except two options that stay off by default: report_issue once the operator sets AMR_ISSUE_TOKEN, and the did:web key check once the operator sets AMR_DID_WEB_RESOLVE=1.

2. Declare it in your MCP client

# Claude Code
claude mcp add amr -- uvx mandatia

# Other MCP clients (Cursor: .cursor/mcp.json): set the three paths
AMR_DB_PATH=/absolute/path/amr_mandates.db
AMR_SIGNING_KEY_PATH=/absolute/path/amr_signing_key.pem
AMR_PUBLIC_KEY_PATH=/absolute/path/amr_signing_key.pub

By default AMR writes its database and its key in the client's current directory. Keep the .pem private key out of version control.

3. Give each side only its own tools

An agent that can create, sign or revoke its own mandate authorizes itself, and the mandate then proves nothing. Set AMR_TOOL_PROFILE in the environment of each client, all pointing at the same AMR_DB_PATH.

ProfileWhoTools
principalthe person or body that grants mandatescreate, sign, revoke, contest, prove
agentthe agent that acts under a mandateverify_mandate, issue_action_token, log_action, issue_mandate_attestation, get_registry_public_key; create_mandate for sub-mandates under its own mandate only
receivera third party the agent acts uponcheck_action_token, get_registry_public_key
full (default)tests and single-user setupsevery tool

In the code on main since 14 November 2026, not yet in the published version 0.1.2: every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). The client uses them to decide which calls need your approval: some only read (verify_mandate, get_proof), others append to the registry (create_mandate, log_action), revoke_mandate is final, register_principal_key and report_issue may reach the network if the operator turns it on. They are hints for the client, not a protection: AMR applies its own rules whatever the client does with them. python -m amr.tools_list shows them tool by tool.

4. The first mandate, in this order

create_mandate, verify_mandate, log_action, issue_mandate_attestation with get_registry_public_key, revoke_mandate, get_proof.

A runnable example, checked by the test suite: uv run python examples/quickstart_agent.py.

Machine-readable summaries: AGENTS.md, the repository's llms.txt, this site's llms.txt, README.

The 19 tools

Grouped by what they are for. Known limits are written next to the tool concerned.

Authorize

  • create_mandate

    Register a mandate, that is the written, dated and signed instruction by which an identified person sets what their agent may do on their behalf. It carries the principal (a person, or a body through its decision), the agent, the scope, the act that gives the signer the power to authorize (delegation of authority, body decision, contract) and the expiry. Every mandate is SHA-256 hashed and chained.

  • register_principal_key

    The principal registers its own Ed25519 public key, so that its mandates can carry its signature.

    Known limit: for an ordinary principal_id, the registry does not check who registers a key (first registration wins), so a valid signature proves possession of that key, not the identity of the person behind it. A did:web identifier closes this gap at the level of a domain name: the key is accepted only if the domain publishes it (network option, off by default).

  • prepare_mandate_signature

    The exact bytes of a mandate for the principal to sign with its own key. An agent cannot sign in its place.

  • prepare_mandate_pdf

    The mandate as a PDF for the principal to read and sign with its own signature tool. The registry does not sign it; once signed, the file goes to attach_signed_mandate_pdf.

  • attach_signed_mandate_pdf

    Checks, offline, the PAdES signature the principal put on that PDF, against the trust roots the operator chose, and records the signer in the proof. It does not read the EU trusted lists, does not check revocation, and does not decide whether the signer may act for the principal.

Lock

  • issue_action_token

    The lock. AMR sits in the token issuance layer. No valid mandate → no Ed25519-signed JWS token → no action possible. Structural enforcement before the act, not audit after. In the open-source code since April 23, 2026.

  • check_action_token

    Re-check an action token with the registry at the moment of acting: the signature proves the authorization at issue time, this says whether it still holds now.

Verify

  • verify_mandate

    Before a sensitive action, the agent checks that its mandate is valid, active and not revoked, and that every mandate above it is too. One call. The answer returns the mandate's scope, it does not judge the action: issue_action_token is what refuses an out-of-scope action.

    In the code on main since 15 November 2026, not yet in the published version 0.1.2: with mandate_id, the answer is about that one mandate. A mandate that is revoked, expired or held by another agent answers no, even if the agent holds another one in force.

  • issue_mandate_attestation

    A signed attestation of a mandate, for the agent to show a third party. The receiver verifies it offline with the registry's public key, without an account.

  • get_registry_public_key

    The registry's public key, for checking attestations and tokens without calling the registry.

Prove

  • log_action

    Log every action taken under a mandate. Each event is hashed, timestamped, and chained to the parent mandate. Tamper-evident audit trail by construction.

  • get_proof

    Generate a cryptographic proof of any mandate or action. SHA-256 chain verification. Tamper-evident. Independently verifiable.

  • export_insurer_dossier

    A signed dossier of a mandate over a period, for an insurer or an auditor: perimeter, status, sub-mandates, actions, tokens and integrity checks. JSON and printable page.

Revoke, contest, report

  • revoke_mandate

    Revoke a mandate now. Final. The mandate and its whole branch of sub-mandates stop at once; tokens already issued are reported until they end.

  • prepare_revocation_signature

    The bytes of a revocation for the principal to sign, when it has a registered key.

  • contest_action

    Record that a principal contests an action an agent already performed: a dated, chained record, one per action, that cannot be edited.

  • prepare_contest_signature

    The bytes of a contest for the principal to sign, when it has a registered key.

  • list_action_contests

    List the contested actions, with a response-deadline reminder chosen by the operator. No legal deadline is computed.

  • report_issue

    Report a problem with AMR itself. Without an operator token, no network call: a pre-filled link to open.