aws-payment-cryptography-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Purpose

This is an MCP server + Claude agent template that connects Claude to AWS Payment Cryptography (APC) via the Model Context Protocol. It targets acquirer/processor use cases — migrating from physical HSMs (Thales payShield, Atalla, Futurex) to APC's managed cloud HSM service. Issuer use cases (card personalization, IMK/CMK derivation) are explicitly out of scope.

Setup and Running

pip install -e .          # installs apc-agent entry point
apc-agent                 # starts MCP server over stdio

AWS credentials are consumed via the standard boto3 credential chain (IAM role, ~/.aws/credentials, environment variables). Set AWS_REGION — the MCP config in .claude/settings.json defaults to us-east-1.

The .claude/settings.json already registers the MCP server for Claude Code:

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

Testing

pytest                          # run all tests
pytest tests/test_compliance.py # run a single file

Test dependencies: pytest, pytest-asyncio, moto[payment-cryptography] (for mocking APC). Defined in pyproject.toml under [tool.hatch.envs.default].

Architecture

src/apc_agent/
├── server.py          — FastMCP server; registers all tool groups; entry point
├── control_plane.py   — Key lifecycle tools (boto3: 'payment-cryptography')
├── data_plane.py      — Cryptographic operation tools (boto3: 'payment-cryptography-data')
├── hsm_tools.py       — HSM legacy code analysis tools (R8 — source analysis only)
├── hsm_analysis.py    — HSM command registry: Futurex + Thales patterns + regex detectors
├── system_prompt.py   — Agent domain knowledge injected as MCP instructions
└── compliance.py      — PCI guard-rail logic: prohibited algorithms, legacy constructs, key usage registry

Two boto3 clients, strict boundary:

• payment-cryptography — control plane (key lifecycle only)
• payment-cryptography-data — data plane (crypto operations only)