jPOS MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jPOS MCP Server build a 0200 message with PAN 4111111111111111 amount 100.00"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
jPOS MCP Server
mcp-name: io.github.mohisyed/jpos-mcp-server
The first open-source MCP server for jPOS and ISO 8583.

Claude validating a real ISO 8583 financial transaction request using deterministic tools. No guessing — every answer comes from verified data.
An MCP server that gives AI agents (Claude, Cursor, VS Code Copilot) deterministic, verified access to ISO 8583 field specs, MTI decoding, jPOS packager XML generation, deploy descriptor validation, message building, and jPOS documentation search.
No more guessing packager class names. No more scrolling a 300-page PDF. Call a tool, get the right answer.
Table of Contents
Related MCP server: maxed-mcp
Quickstart
Prerequisites: Python 3.11+ and uv package manager.
# 1. Clone and install
git clone https://github.com/mohisyed/JPOS-MCP.git
cd JPOS-MCP
uv sync
# 2. (Optional) Set up the knowledge base for semantic search
mkdir -p knowledge/sources
curl -o knowledge/sources/proguide.pdf https://jpos.org/doc/proguide-draft.pdf
uv run python knowledge/ingest.py
# 3. Add to Claude Desktop (see Claude Desktop Setup below)All 6 tools work immediately after step 1. Step 2 enables the search_jpos RAG tool with real documentation.
Tools
Tool | Namespace | What It Does | Example Input |
|
| Return full ISO 8583 field spec (name, format, jPOS class, max length) |
|
|
| Decode MTI into version, class, function, origin + expected response |
|
|
| Generate complete GenericPackager XML from plain English |
|
|
| Lint a Q2 deploy descriptor (channel, QMUX, TM rules) |
|
|
| Validate ISO 8583 field dict (mandatory fields, lengths, PAN safety) |
|
|
| Semantic search over jPOS Programmer's Guide (RAG) |
|
Why deterministic tools instead of LLM inference?
LLMs can guess that field 35 uses IFA_LLVAR, but they sometimes hallucinate class names like IFA_LLTRACK2 (doesn't exist). Our tools read from data/iso_fields.json — a verified lookup table — so the answer is always correct. The AI decides which tool to call; our code provides the facts.
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ AI AGENT CLIENTS │
│ Claude Desktop · Claude API · Cursor · VS Code Copilot │
└──────────────────────────┬──────────────────────────────────────┘
│ MCP Protocol (JSON-RPC 2.0)
stdio (local) / Streamable HTTP (Docker)
│
┌──────────────────────────▼──────────────────────────────────────┐
│ jpos-mcp-server (Python / FastMCP v3.1.1) │
│ │
│ main.py │
│ ├── iso_server [iso] lookup_field, decode_mti │
│ ├── jpos_server [jpos] generate_packager, validate_descriptor│
│ ├── msg_server [msg] build_message │
│ └── rag_server [docs] search_jpos │
│ │
│ ┌──────────────┐ ┌─────────────────────────────────────────┐ │
│ │ DATA LAYER │ │ KNOWLEDGE LAYER │ │
│ │ iso_fields │ │ ChromaDB + sentence-transformers │ │
│ │ mti_table │ │ Chunked jPOS Programmer's Guide │ │
│ │ mandatory │ │ + project docs (ISO 8583 deep dive) │ │
│ └──────────────┘ └─────────────────────────────────────────┘ │
│ core/ — timeout guardrails, PAN detection, safe logging │
└──────────────────────────────────────────────────────────────────┘Sub-server composition
The server is split into 4 domain-specific sub-servers mounted via FastMCP.mount(). Each sub-server is independently testable — a bug in the RAG pipeline doesn't prevent ISO field lookups from working. Adding a new domain is one file + one mount() call in main.py.
Timeout guardrails
Every tool is wrapped with @with_timeout() using asyncio.wait_for(). If a tool hangs (e.g., ChromaDB cold start), it returns a structured error dict instead of blocking the entire MCP server. Timeout tiers:
Tier | Timeout | Tools |
Fast | 2s |
|
Medium | 5s |
|
Slow | 10s |
|
RAG | 15s |
|
Testing
Why we test
Payment systems have zero tolerance for wrong answers. A bad packager class name (IFA_LLVAR vs IFB_LLHEX) causes cryptic byte-level parsing errors that take hours to debug. Our tests verify that every tool returns correct, deterministic results across all input types.
Running tests
# Install dev dependencies (pytest, ruff, black, coverage)
uv sync --dev
# Run all 114 tests (unit + MCP integration + E2E workflows)
uv run pytest tests/ -v
# Run a single test file
uv run pytest tests/test_iso.py -v
# Run a single test function
uv run pytest tests/test_iso.py::test_decode_mti_request -v
# Run with coverage report (target: 80%+, current: 91%)
uv run pytest tests/ --cov=servers --cov=core --cov-report=term-missing
# Lint (must pass with zero errors)
uv run ruff check .
# Format
uv run black .Test structure (114 tests, 3 layers)
File | Layer | What it covers |
| unit |
|
| unit |
|
| unit |
|
| unit | Query expansion, mock collection responses, empty collection handling |
| unit |
|
| unit |
|
| unit |
|
| integration | Tool registration, JSON Schema generation, end-to-end MCP protocol calls |
| E2E workflow | Multi-step workflows: Visa auth packager build, reversal debugging, deploy descriptor validation, security boundary, RAG via MCP, system health, error handling |
Writing new tests
When adding a tool, cover three categories:
Happy path — valid input returns expected output
Invalid input — bad types, out-of-range values, malformed data return structured errors
Edge cases — boundary values, empty inputs, PCI-sensitive data
All tools are async def, so use @pytest.mark.asyncio:
@pytest.mark.asyncio
async def test_my_new_tool():
result = await my_tool("valid input")
assert result["expected_key"] == "expected_value"Knowledge Base (RAG)
The search_jpos tool uses two-stage hybrid retrieval over jPOS documentation: a bi-encoder (mpnet) for fast candidate retrieval, followed by a cross-encoder reranker for high-precision ordering.
How it works
Ingestion — PDFs and markdown files are cleaned (boilerplate, TOC dot-leaders, page headers stripped) and split into 200-word chunks with 40-word overlap. Low-signal chunks are filtered out at ingest time.
Embedding — Each chunk is encoded into a 768-dimensional vector using
all-mpnet-base-v2and stored in ChromaDB.Query expansion — Short or jargon-heavy queries (e.g. "STAN", "IFB_LLHEX") get domain context added before embedding so the model has enough signal to disambiguate.
Stage 1 retrieval — Top 25 candidates fetched via cosine similarity.
Stage 2 rerank — Cross-encoder (
ms-marco-MiniLM-L-6-v2) scores each(query, chunk)pair by attending across both inputs. This is significantly more accurate than cosine alone.Display score — Combination of cross-encoder + cosine + rank-position bonus, returned as the top 5 chunks.
The cross-encoder loads lazily on first call (~1s). Falls back to keyword-overlap reranking if the model can't load (offline environments).
Setting up the knowledge base
# Download the jPOS Programmer's Guide (5.3MB PDF)
mkdir -p knowledge/sources
curl -o knowledge/sources/proguide.pdf https://jpos.org/doc/proguide-draft.pdf
# Run ingestion (first run downloads ~80MB mpnet + ~80MB cross-encoder)
uv run python knowledge/ingest.pyThe ingest script processes:
PDFs from
knowledge/sources/*.pdf— page-by-page chunking with cleanupMarkdown from
docs/*.md— section-aware chunking (splits on##headings)Markdown from
knowledge/sources/*.md— for any additional docs you add
Ingestion is idempotent — running it again skips existing chunks and only adds new ones.
Default knowledge base after a full ingest: ~786 chunks across the jPOS Programmer's Guide, ISO 8583-1:2003 spec, Wikipedia reference, jPOS tutorial pages, and project docs.
Adding your own documents
Drop any .pdf or .md files into knowledge/sources/ and re-run:
uv run python knowledge/ingest.pyGood candidates:
ISO 8583 reference guides
Your organization's interchange spec documentation
jPOS tutorial pages (save as markdown)
GenericPackager XML examples with annotations
Search quality
Scores are calibrated for the cross-encoder + mpnet pipeline:
Score | Quality | Meaning |
0.55+ | Strong | Direct answer in the chunk |
0.40–0.55 | Good | Relevant context, may need synthesis |
0.25–0.40 | Partial | Tangentially related |
<0.25 | (filtered) | Below noise floor — not returned |
Benchmark across 25 representative queries: 0.886 average score, 100% strong results.
Docker
Build and run
# Build and start (HTTP transport)
docker compose -f docker/docker-compose.yml up -d --build
# View logs
docker compose -f docker/docker-compose.yml logs -f
# Re-ingest docs after adding new sources
docker compose -f docker/docker-compose.yml exec jpos-mcp uv run python knowledge/ingest.py
# Check health
docker compose -f docker/docker-compose.yml exec jpos-mcp curl -sf http://localhost:8000/healthDocker architecture
Base image:
python:3.11-slimEmbedding model pre-downloaded at build time (avoids 30-60s cold start)
Non-root user (
appuser:1001) for securityPersistent volume for ChromaDB data (survives container restarts)
Healthcheck every 30s on
/health
Claude Desktop with Docker
{
"mcpServers": {
"jpos-expert": {
"url": "http://localhost:8000/mcp"
}
}
}Claude Desktop Setup
macOS
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"jpos-expert": {
"command": "uv",
"args": ["run", "python", "main.py"],
"cwd": "/ABSOLUTE/PATH/TO/JPOS-MCP"
}
}
}Windows
Edit %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"jpos-expert": {
"command": "uv",
"args": ["run", "python", "main.py"],
"cwd": "C:\\ABSOLUTE\\PATH\\TO\\JPOS-MCP"
}
}
}After saving, restart Claude Desktop. All tools appear in the hammer (tools) menu.
Verifying it works
Ask Claude: "What's the jPOS packager class for field 35?"
Claude should call lookup_field(35) and return the exact spec — IFA_LLVAR for ASCII, IFB_LLHEX for BCD — not a guess.
MCP Inspector
The MCP Inspector is a browser-based UI for testing tools interactively:
uv run fastmcp dev inspector main.py:mcpThis opens a browser at http://localhost:6274 where you can:
See all registered tools and their JSON Schema
Call any tool with custom inputs
Inspect responses in real time
Debug tool errors without needing Claude Desktop
Security
This server is designed with PCI DSS awareness:
Real PANs are rejected — The Luhn algorithm detects real card numbers in any tool input. Only test PANs (
4111111111111111,5500005555555559, etc.) are accepted. This runs before any other processing.Sensitive fields redacted from logs —
PaymentSafeFormatterstrips fields 2 (PAN), 35 (Track 2), 45 (Track 1), 52 (PIN), 55 (EMV), and 64 (MAC) from all log output.stderr-only logging — stdout is reserved for the JSON-RPC stream (stdio transport). A single
print()would corrupt the protocol.Non-root Docker — Container runs as
appuser:1001.No credentials — The server stores no keys, tokens, or secrets.
Pinned dependencies —
fastmcp==3.1.1exact pin prevents supply chain surprises.Hardcoded tool descriptions — Tool descriptions are in Python decorators, never loaded from external data (prevents injection).
What must never pass through this server
Data | Reason |
Real PANs | PCI DSS Requirement 3 |
Track 1/2/3 data | Prohibited after authorization |
CVV/CVV2/CVC2 | PCI DSS 3.2.1 |
Real cryptographic keys | HSM-managed only |
PIN blocks | Must not traverse uncontrolled layers |
Troubleshooting
ModuleNotFoundError: No module named 'fastmcp'
Dependencies aren't installed. Run:
uv syncsearch_jpos returns "Knowledge base not initialized"
ChromaDB hasn't been populated. Run:
mkdir -p knowledge/sources
curl -o knowledge/sources/proguide.pdf https://jpos.org/doc/proguide-draft.pdf
uv run python knowledge/ingest.pyClaude Desktop doesn't show tools
Check that
cwdinclaude_desktop_config.jsonis an absolute pathMake sure
uvis in your PATH (try runninguv --versionin terminal)Restart Claude Desktop completely (quit + reopen, not just close window)
Tests fail with import errors
Make sure you installed dev dependencies:
uv sync --devprint() broke the stdio transport
Any stdout output corrupts JSON-RPC. Find and remove print() statements. Use logging.getLogger(__name__).info() instead — it writes to stderr.
Timeout errors on search_jpos
First call after startup can take 5-10s (ChromaDB + embedding model cold start). The 15s timeout accommodates this. If it persists, check that knowledge/chroma_db/ exists and has data.
Roadmap
V1 — MVP — 6 tools, Claude Desktop, Docker, 114 tests (91% coverage), cross-encoder reranked RAG, GitHub Actions CI/security, issue templates, SECURITY.md
V2 — Enhanced — Java sidecar (live pack/unpack), custom interchange specs, jPOS log parser, OAuth 2.1, PyPI package, MCP registry submission
V3 — Platform — Hosted deployment, multi-spec (Visa/MC/Amex/Discover), horizontal scaling, transaction analytics
See docs/roadmap-and-architecture.md for full details.
Contributing
See CONTRIBUTING.md for setup instructions and guidelines.
License
Available Tools
7 toolsdocs_search_jposA
Search jPOS documentation using hybrid semantic + keyword search.
Returns up to 5 matches with source, section, page, and similarity score. Scores are calibrated for the all-mpnet-base-v2 embedding model combined with a keyword overlap rerank:
strong >= 0.55 (direct answer expected in chunk)
good >= 0.40 (relevant context, may need synthesis)
partial >= 0.25 (tangentially related) Chunks below 0.25 are filtered out as noise.
Pipeline:
Expand short/jargon queries with domain context
Embed the expanded query and fetch top 15 candidates by cosine
Rerank candidates with keyword overlap from the original query (70% cosine + 30% keyword overlap)
Return top 5
Why return raw chunks instead of summarizing: the calling LLM can reason about conflicting chunks, notice version differences, and assess confidence from similarity scores. Pre-summarizing loses this nuance.
Inputs: query (required). Returns: result
healthA
Return server health status: version, tool count, and ChromaDB chunk count.
Inputs: no named parameters. Returns: object
iso_decode_mtiA
Decode a 4-digit MTI into version, message class, function, and origin. For request messages (function digit = 0), returns the expected response MTI.
Inputs: mti (required). Returns: object
iso_lookup_fieldA
Return the complete ISO 8583 specification for a data element number. Returns: name, format (FIXED/LLVAR/LLLVAR), type, max_length, jpos_class_bcd, jpos_class_ascii, mandatory_for_mtis, pci_sensitive, notes. Use this before writing any GenericPackager XML.
Inputs: field_number (required). Returns: object
jpos_generate_packagerA
Generate a complete jPOS GenericPackager XML configuration. Parses field numbers from description, looks up correct jPOS classes, and assembles valid XML ready to save as a .xml file. Always includes fields 0 (MTI) and 1 (Bitmap).
Why this doesn't use an LLM: LLM-generated XML can contain hallucinated class names. This uses iso_fields.json as ground truth — always correct.
Inputs: description (required). Returns: result
jpos_validate_descriptorA
Validate a jPOS Q2 deploy descriptor XML file. Checks: well-formed XML, required attributes, channel/QMUX/TM-specific rules, common property name typos.
Inputs: xml_content (required). Returns: object
msg_build_messageA
Validate an ISO 8583 message field dictionary. Checks MTI validity, missing mandatory fields, value length violations, and potential real PANs (detected via Luhn algorithm — rejected for safety). Only test PANs (4111111111111111 etc.) are accepted.
Inputs: fields (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose covering documentation search, health status, ISO 8583 MTI decoding, field lookup, packager generation, descriptor validation, and message building. No overlap or ambiguity exists.
Names use mixed conventions: some start with 'jpos_', some with 'iso_', one with 'msg_', and one is just 'health'. While all are snake_case and mostly verb_noun, the lack of a uniform prefix or structure reduces consistency.
With 7 tools, the server covers essential areas of jPOS configuration and ISO 8583 operations without being overwhelming. The scope is well-scoped for development and validation tasks.
The set covers documentation search, health, MTI decoding, field specs, packager generation, descriptor validation, and message validation. Missing encoding/decoding of raw messages is a minor gap but the core workflow is supported.
Maintenance
Related MCP Connectors
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server that enables AI agents to parse, validate, and reverse ISO 20022 bank statements, with tools for discovering message types and return reasons.2490 PyPI2Apache 2.0
- AlicenseNot gradedqualityCmaintenanceMCP server providing deterministic accounting tools for AI agents, including bank statement parsing, document classification, money math, and webhook verification.2Apache 2.0
- AlicenseAqualityBmaintenanceAn MCP server that exposes the pacs008 ISO 20022 FI-to-FI Customer Credit Transfer library as tools for AI agents and assistants, enabling generation, validation, and parsing of pacs.008 credit transfer XML messages.1645 PyPI1Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that provides AI agents with tools to validate SWIFT MT and ISO 20022 MX payment messages, check BIC/IBAN correctness, and convert between MT and MX formats.74 npmMIT