Docs · AI agent signing
AI agents & MCP connector
MCP connector URL
Streamable HTTP endpoint (production):
https://mcp.liminalkeys.com/mcp
Console → AI agents shows the same URL with a copy button.
Response envelopes are ES256-signed; public keys are at
https://mcp.liminalkeys.com/.well-known/liminalkeys-mcp-keys.json (kid mcp-response-v1).
Claude setup (plugin 0.1.10)
The recommended path is the official Liminal Keys Claude plugin
(liminal-keys 0.1.10). It installs the liminalkeys-sign skill and wires the MCP
connector to https://mcp.liminalkeys.com/mcp.
Connect the MCP server (URL only)
Add the MCP URL above in Claude and choose Connect. Sign in with your Liminal Keys account (Google, Apple, Microsoft work or school, or email code — the same options as Console). Authentication uses URL-only OAuth with automatic client registration: you do not paste a client ID, client secret, or other OAuth app credentials in advanced settings. If you have multiple AI agents in Console, pick which connection this connector should use when prompted.
Claude Code
Add the marketplace, install or update the plugin, then start a session:
/plugin marketplace add LiminalKeys/claude-plugin
/plugin install liminal-keys@liminal-keys
claude.ai
- Open Customize → Plugins.
- Add or refresh the GitHub marketplace LiminalKeys/claude-plugin.
- Enable the Liminal Keys plugin and connect the bundled MCP URL with Connect (URL-only sign-in as above).
Skill zip without the plugin
Same skill version the plugin bundles (offline wheels, SHA-256 sidecar):
Upload the zip in Claude Skills, or extract and point the sandbox at the inner liminalkeys-sign/ folder.
Optional: API key header (non-OAuth clients)
Some hosts do not support MCP OAuth yet. You can send a Console-issued lkag_… key in
x-api-key instead (one auth mode per request — not both OAuth and a key).
Issue a 30- or 90-day key in Console → AI agents if you use this path.
MCP tools (four)
list_certificates— allowed signing certificates (client_noncerequired)get_certificate_chain— chain envelope + leaf PEM (certificate_id,client_nonce)sign_hash— RSA signature over a 32-byte digest (digest_base64,document_label,client_nonce; optionalapproval_id,poll_timeout_seconds0–120 default 120,previews)timestamp— optional RFC 3161 via FreeTSA (non-qualified, off unless requested)
prepare, embed, and validate run locally via liminal-sign — not as MCP tools.
Signing flow (liminalkeys-sign 0.1.10)
One certificate lookup per attempt, then prepare → sign → finish. Do not re-list certificates or re-fetch the chain mid-flow.
-
1
MCP: certificates (once each)
list_certificateswithclient_nonce, thenget_certificate_chainwith a new nonce. Save chain PEM locally (for examplechain.pem). -
2
Local: prepare
liminal-sign prepare --pdf "$PDF" --cert-chain chain.pem \ --out state.json --document-label "Contract Q4"Hashes the PDF in the sandbox, builds approval previews, and prepares CMS state. Use
digest_base64andpreviewsfromstate.jsononsign_hash. -
3
MCP: sign_hash (one approval when required)
Call once with the same
client_noncefrom step 1. Long-poll up to 120 seconds. When policy requires approval, approvers act in LK Approvals or on their phone.Resume: After approval, if the call times out or returns
pending_approval, callsign_hashagain with the samedigest_base64,client_nonce, andapproval_id. That collects the signature — it does not create a second approval. Never mint a new nonce after approval. -
4
Local: finish
liminal-sign finish --state state.json --mcp-sign-envelope sign.json \ --expected-nonce "$NONCE" --output signed.pdfEmbeds the signature, runs mandatory validation, and prints the report. Non-zero exit means not successfully signed.
Branded visible stamp (default)
Skill 0.1.10 adds a branded Liminal Keys stamp by default: last page,
bottom-right, 248×96 pt, with dates in the signer’s local timezone
(override with --stamp-locale / --stamp-timezone on prepare).
For a cryptographic signature with no on-page mark, add --invisible-signature on prepare.
Approvals and previews
When policy requires approval, include at least one small PNG in sign_hash previews on the
first call — prepare supplies these in state.json. Previews are
agent-rendered context for approvers (unverified). See LK Approvals.
Console setup
- Open Console → AI agents.
- Create an agent (for OAuth connector binding and optional API keys).
- In Policy rules, add a rule with subject type AI agent and allow, require approval, or deny.
- Review outcomes in Sign audit (document label and DigestHashHex — first 16 hex characters in the table, copy for the full 64-character SHA-256 hash).
Sample prompts
| Prompt | Flow |
|---|---|
| List the signing certificates my Liminal Keys agent is allowed to use, with subject and expiry. | list_certificates, get_certificate_chain |
| Sign contract.pdf with our certificate and show the validation report. | chain → prepare → sign_hash → finish (branded stamp by default) |
| Sign contract.pdf with no visible stamp. | prepare --invisible-signature → sign_hash → finish |
| Get a detached signature for the SHA-256 of release-manifest.json labelled “Release 2.1.0 manifest”. | sign_hash (format-agnostic) |
| My signing request is waiting for approval. Keep waiting and finish once approved. | Retry sign_hash with same approval_id + client_nonce, then finish |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| 401 Unauthorized | Missing or invalid OAuth session or API key | Reconnect the MCP URL (Connect) or re-issue lkag_…; use one auth mode only |
| 403 Forbidden | Conflicting auth headers, or token missing agent connection claim | Single header only for API key path; reconnect OAuth for connector path |
denied | No matching allow rule or explicit deny | Fix policy; do not retry the same request |
pending_approval after 120s | Approvers have not acted yet | Call sign_hash again with same approval_id and client_nonce |
| Duplicate approvals | New client_nonce or new attempt after approval | Reuse the same nonce and approval_id to collect the signature; retries do not open a second approval |
finish / validate failed | Trust anchor or stale state | Use correct chain PEM; do not re-run prepare after sign_hash; show full report |
preview_warnings | Malformed preview image | Fix PNG/JPEG and call sign_hash again on first attempt |
Plugin vs skill vs MCP · LK Approvals (PWA) · Console · Security