Docs · AI agent signing

AI agents & MCP connector

AI agent signing — not Mac/Xcode or CI app signing (see App & code signing). Workspace AI agents (for example Claude) sign through the same policy engine as other signers, with optional human approval. Private keys stay in Key Vault; agents never receive key material. Open Console → AI agents to register connectors and issue API keys. New here? Read Plugin vs skill vs MCP connector first.

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

To upgrade an existing install, run the same install command again after refreshing the marketplace.

claude.ai

  1. Open Customize → Plugins.
  2. Add or refresh the GitHub marketplace LiminalKeys/claude-plugin.
  3. 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_nonce required)
  • 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; optional approval_id, poll_timeout_seconds 0–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. 1

    MCP: certificates (once each)

    list_certificates with client_nonce, then get_certificate_chain with a new nonce. Save chain PEM locally (for example chain.pem).

  2. 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_base64 and previews from state.json on sign_hash.

  3. 3

    MCP: sign_hash (one approval when required)

    Call once with the same client_nonce from 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, call sign_hash again with the same digest_base64, client_nonce, and approval_id. That collects the signature — it does not create a second approval. Never mint a new nonce after approval.

  4. 4

    Local: finish

    liminal-sign finish --state state.json --mcp-sign-envelope sign.json \
      --expected-nonce "$NONCE" --output signed.pdf

    Embeds 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

  1. Open Console → AI agents.
  2. Create an agent (for OAuth connector binding and optional API keys).
  3. In Policy rules, add a rule with subject type AI agent and allow, require approval, or deny.
  4. 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

PromptFlow
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

SymptomCauseFix
401 UnauthorizedMissing or invalid OAuth session or API keyReconnect the MCP URL (Connect) or re-issue lkag_…; use one auth mode only
403 ForbiddenConflicting auth headers, or token missing agent connection claimSingle header only for API key path; reconnect OAuth for connector path
deniedNo matching allow rule or explicit denyFix policy; do not retry the same request
pending_approval after 120sApprovers have not acted yetCall sign_hash again with same approval_id and client_nonce
Duplicate approvalsNew client_nonce or new attempt after approvalReuse the same nonce and approval_id to collect the signature; retries do not open a second approval
finish / validate failedTrust anchor or stale stateUse correct chain PEM; do not re-run prepare after sign_hash; show full report
preview_warningsMalformed preview imageFix PNG/JPEG and call sign_hash again on first attempt

Plugin vs skill vs MCP · LK Approvals (PWA) · Console · Security