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.
| Profile | Who | Tools |
|---|---|---|
principal | the person or body that grants mandates | create, sign, revoke, contest, prove |
agent | the agent that acts under a mandate | verify_mandate, issue_action_token, log_action, issue_mandate_attestation, get_registry_public_key; create_mandate for sub-mandates under its own mandate only |
receiver | a third party the agent acts upon | check_action_token, get_registry_public_key |
full (default) | tests and single-user setups | every 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. Adid:webidentifier 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_tokenis 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.