AWS Payment Cryptography MCP server

AWS Payment Cryptography MCP Server

An MCP server for AWS Payment Cryptography (APC). Gives AI coding assistants direct access to the APC control plane (key lifecycle) and data plane (cryptographic operations), along with embedded knowledge of payment standards, HSM vendor command sets, and PCI PIN v3.1 compliance requirements. This tool is for development and testing purposes only and should not be used directly within a production system. It is designed to accelerate the 'Proof of Concept' phase and migration analysis by providing a domain-aware interface for AWS Payment Cryptography. Works with Claude Code, Codex CLI, and any MCP-compatible client.

There are three reasons to use this:

1. You're building a new acquirer or processor integration on APC and want an AI co-pilot that understands the domain — key hierarchies, DUKPT, TR-31/TR-34, PIN formats, compliance constraints — without reading documentation for every API call.

1. You have existing code that runs against a Thales payShield 10K or Futurex Excrypt Enterprise SSP v.2 and want to understand what it's doing before migrating to APC.

1. You're using apc-hsm-proxy to move an application to APC without refactoring it, and need to build handlers for the specific commands your application sends.

Issuer functions — card personalization, IMK/CMK derivation, issuer script processing — are out of scope. A small number of issuer-adjacent APC operations (PIN generation schemes, EMV secure messaging) are exposed for completeness but are not the focus. This is a template, not a production system.

Architecture & Trust Boundaries

graph LR
      subgraph "Your Local Host"
          A[AI Client] <--> B[MCP Server]
          B --> G([Boto3])
      end
      subgraph "Your AWS Account"
          D[APC Control Plane]
          E[APC Data Plane]
      end
      subgraph "Your LLM Provider"
          F[LLM API]
      end

      G --> D
      G --> E
      A <-- "Prompts/Responses" --> F
      D ~~~ F
      D ~~~ E

Setup

pip install -e .
apc-agent        # starts the MCP server over stdio

The MCP server is client-agnostic — it speaks the standard Model Context Protocol over stdio and works with any MCP-compatible client. .claude/ contains Claude Code settings; .codex/ is the Codex CLI equivalent. Neither is required to run the server itself.

Claude Code — .claude/settings.json in this repo registers the server automatically. For Claude Desktop, add the same block to ~/Library/Application Support/Claude/claudedesktopconfig.json (macOS) or %APPDATA%\Claude\claudedesktopconfig.json (Windows):

{
  "mcpServers": {
    "apc-agent": {
      "command": "apc-agent",
      "env": { "AWS_REGION": "us-east-1" }
    }
  }
}

Codex CLI — .codex/config.toml in this repo registers the server automatically. For user-level registration (applies across all projects), add the same block to ~/.codex/config.toml:

[mcp_servers.apc-agent]
command = "apc-agent"
env = { AWS_REGION = "us-east-1" }

Or register via the CLI:

Shortened. The full README is on GitHub.