How do I use jPOS MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by mohisyed

Overview Schema Related Servers Score Discussions

Python

Hybrid

jPOS MCP Server

mcp-name: io.github.mohisyed/jpos-mcp-server

The first open-source MCP server for jPOS and ISO 8583.

License: MIT Python 3.11+ Tests Coverage

Demo

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.

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
`lookup_field`	`iso`	Return full ISO 8583 field spec (name, format, jPOS class, max length)	`field_number: 35`
`decode_mti`	`iso`	Decode MTI into version, class, function, origin + expected response	`mti: "0200"`
`generate_packager`	`jpos`	Generate complete GenericPackager XML from plain English	`"Visa auth fields 2,3,4,7,11,35,41,42 BCD"`
`validate_descriptor`	`jpos`	Lint a Q2 deploy descriptor (channel, QMUX, TM rules)	`xml_content: "<qmux>..."`
`build_message`	`msg`	Validate ISO 8583 field dict (mandatory fields, lengths, PAN safety)	`{"0":"0200", "2":"4111..."}`
`search_jpos`	`docs`	Semantic search over jPOS Programmer's Guide (RAG)	`"How to configure QMUX"`

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	`lookup_field`, `decode_mti`
Medium	5s	`build_message`, `validate_descriptor`
Slow	10s	`generate_packager`
RAG	15s	`search_jpos`

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
`test_iso.py`	unit	`lookup_field`, `decode_mti` — valid/invalid fields, MTI categories
`test_jpos_tools.py`	unit	`generate_packager` (BCD/ASCII), `validate_descriptor` (QMUX, channel-adaptor, txnmgr, malformed XML)
`test_message.py`	unit	`build_message` — valid messages, missing fields, length violations, PAN rejection
`test_rag.py`	unit	Query expansion, mock collection responses, empty collection handling
`test_timeout.py`	unit	`@with_timeout` — guardrail fires, fast passes, exceptions caught
`test_validators.py`	unit	`luhn_check`, `contains_likely_real_pan` — Luhn edge cases, separators, test PAN whitelist
`test_logging.py`	unit	`PaymentSafeFormatter` redaction, stderr handler config
`test_mcp_integration.py`	integration	Tool registration, JSON Schema generation, end-to-end MCP protocol calls
`test_e2e.py`	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-v2 and 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.py

The ingest script processes:

PDFs from knowledge/sources/*.pdf — page-by-page chunking with cleanup
Markdown 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.py

Good 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/health

Docker architecture

Base image: python:3.11-slim
Embedding model pre-downloaded at build time (avoids 30-60s cold start)
Non-root user (appuser:1001) for security
Persistent 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:mcp

This 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 — PaymentSafeFormatter strips 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.1 exact 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 sync

`search_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.py

Claude Desktop doesn't show tools

Check that cwd in claude_desktop_config.json is an absolute path
Make sure uv is in your PATH (try running uv --version in terminal)
Restart Claude Desktop completely (quit + reopen, not just close window)

Tests fail with import errors

Make sure you installed dev dependencies:

uv sync --dev

`print()` 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

MIT

Available Tools

7 tools

docs_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.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Natural language question about jPOS configuration or usage.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It comprehensively discloses the retrieval pipeline (query expansion, embedding, reranking), score calibration thresholds, and the rationale for returning raw chunks instead of summaries.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear front-loaded purpose, followed by return format, score calibration, pipeline, and rationale. Each sentence provides useful information, though the pipeline detail may be slightly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema shown), the description covers query processing, scoring, and return format. It could mention potential errors or rate limits, but overall is fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear parameter description. The tool description adds value by explaining how the query is expanded and used in the pipeline, going beyond the schema's basic description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Search jPOS documentation using hybrid semantic + keyword search.' It specifies the resource (jPOS documentation) and action (search), and is distinct from sibling tools like iso_decode_mti or msg_build_message.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for searching documentation but does not explicitly state when to use this tool versus alternatives or provide any when-not guidance. No mention of other tools or conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

healthA

Return server health status: version, tool count, and ChromaDB chunk count.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It explicitly states the tool returns data (version, counts) implying no side effects. It could mention idempotency or safety, but for a health check, this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no wasted words. The main purpose is front-loaded. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and existence of an output schema, the description adequately covers the return fields. It is likely sufficient for an agent to understand what the tool provides.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema coverage is 100% trivially. The description does not need to explain parameters. Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns server health status including specific fields (version, tool count, ChromaDB chunk count). This distinguishes it from sibling tools which deal with ISO messages and document search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While no explicit when-to-use guidance is given, the tool name and description make its purpose obvious. Since siblings are all unrelated, no alternative is needed. The context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`mti`	Yes	4-digit ISO 8583 MTI string.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the tool decodes into four components and provides special behavior for request messages. However, it does not mention auth needs, rate limits, or side effects, though as a decode operation these are minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main function, then a useful additional detail. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple decode tool with one parameter and an output schema (not provided but assumed), the description explains the decoding result and request-response behavior. It does not detail output format, but the existence of an output schema mitigates that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with the schema already describing the mti parameter as a 4-digit ISO 8583 MTI string with pattern and length constraints. The tool description repeats '4-digit MTI' but adds no new semantic information beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it decodes a 4-digit MTI into version, message class, function, and origin. The verb 'Decode' and resource 'MTI' are specific, and the tool distinguishes itself from siblings like iso_lookup_field.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a specific usage hint: for request messages (function digit = 0), it returns the expected response MTI. This helps the agent understand a special case but does not explicitly state when to use this tool over alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`field_number`	Yes	ISO 8583 data element number between 1 and 128.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It lists all returned fields (name, format, type, etc.), disclosing output content. Although it does not explicitly state read-only nature, the lookup behavior is obvious and no side effects are implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences) and well-structured: first sentence states purpose, second details return fields, third gives usage advice. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, full schema coverage, and presence of an output schema, the description is complete. It covers what, how, and when to use, satisfying all informational needs for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the parameter description matches the schema. The description adds no new meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Return the complete ISO 8583 specification for a data element number', using a specific verb and resource. It distinguishes itself from siblings like iso_decode_mti or msg_build_message by focusing on field specification lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises 'Use this before writing any GenericPackager XML', providing clear context for when to use the tool. However, it does not mention when not to use or suggest alternatives, slightly reducing the score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`description`	Yes	Plain English description of the packager. Include field numbers and optionally encoding type (BCD or ASCII). Example: 'Visa auth packager for fields 0,2,3,4,7,11,22,35,41,42 using BCD'

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that it uses a JSON file for accurate class names, is deterministic, and always includes mandatory fields. With no annotations, it carries the burden well, though it could mention error handling or permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise paragraphs, front-loaded with purpose, every sentence informative. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given single parameter with full schema coverage and presence of output schema, description covers input, process, and output purpose adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with a good description and example. Tool description adds value by explaining how the parameter is used (parse field numbers, optionally encoding type), going beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it generates a jPOS GenericPackager XML configuration, explains the process (parsing fields, looking up classes, assembling XML), and specifies it always includes fields 0 and 1. This distinguishes it from siblings like iso_decode_mti or iso_lookup_field.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context on why this tool is reliable (uses iso_fields.json ground truth vs LLM hallucinations), implying when to use it. However, lacks explicit exclusions or direct comparisons to sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`xml_content`	Yes	Full XML content of a jPOS Q2 deploy descriptor file.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so description carries the burden. It describes validation checks but does not explicitly state read-only nature, error handling, or performance characteristics. Adds value beyond 'validate' but not fully comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences: first states purpose, second lists checks. No fluff, every sentence adds value. Front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one parameter, high schema coverage, and an output schema, the description is sufficient for an agent to understand and invoke the tool. Lacks usage guidelines but otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear parameter description. The tool description reinforces the XML content type and checks but adds minimal additional semantics beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool validates a jPOS Q2 deploy descriptor XML file, listing specific checks (well-formed XML, required attributes, rules, typos). This distinguishes it from sibling tools like docs_search_jpos or health.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While no explicit when-to-use or alternatives, the purpose is self-explanatory and siblings are unrelated, making context clear. Lacks explicit 'when not to use' guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`fields`	Yes	Dict mapping field number strings to values. Field "0" must be the MTI. Example: {"0": "0200", "2": "4111111111111111", "3": "000000"}

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It disclose key behaviors (rejects real PANs for safety via Luhn, checks MTI, mandatory fields, length). However, it does not describe what happens on failure or output format, which limits transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (4 sentences) and front-loaded with the main purpose. Each sentence adds valuable detail without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema, the description adequately covers the tool's validation criteria. It could elaborate on error behavior, but overall it provides sufficient context for a validation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add new parameter-specific meaning beyond the schema example; it explains the validation logic but not the parameter structure itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool validates an ISO 8583 message field dictionary, with specific checks (MTI, mandatory fields, length, PANs). This distinguishes it from siblings like iso_decode_mti and iso_lookup_field, which have distinct purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (for validation of field dictionaries) but does not explicitly state when not to use it or suggest alternatives. Context is clear but lacks exclusionary guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

7 tool updatesv0.1.1Jun 21, 2026
- First observeddocs_search_jpos
- First observedhealth
- First observediso_decode_mti
- First observediso_lookup_field
- First observedjpos_generate_packager
- First observedjpos_validate_descriptor
- First observedmsg_build_message

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Disambiguation5/5

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.

Naming Consistency3/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

secureflows-mcp A
io.github.michal-lefler
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Code Analysis Developer Tools Security
181
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2

Related MCP Servers

camt053-mcp
Finance Data Platforms
sebastienrousseau
F
license
A
quality
A
maintenance
MCP server that enables AI agents to parse, validate, and reverse ISO 20022 bank statements, with tools for discovering message types and return reasons.
Updated 6 days ago (2026-08-31 14:18 UTC)
24
1
-
maxed-mcp
Finance Payments & Billing
Maxed-OSS
A
license
Not graded
quality
D
maintenance
MCP server providing deterministic accounting tools for AI agents, including bank statement parsing, document classification, money math, and webhook verification.
Updated 2 months ago (2026-07-05 04:12 UTC)
1
Apache 2.0
pacs008-mcp
Finance Payments & Billing
sebastienrousseau
F
license
A
quality
A
maintenance
An 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.
Updated 8 days ago (2026-08-29 18:44 UTC)
16
1
-
swift-iso20022-mcp
techybiky
A
license
A
quality
C
maintenance
An 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.
Updated 2 months ago (2026-07-18 11:15 UTC)
7
15
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mohisyed/JPOS-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

jPOS MCP Server

Table of Contents

Quickstart

Tools

Why deterministic tools instead of LLM inference?

Architecture

Sub-server composition

Timeout guardrails

Testing

Why we test

Running tests

Test structure (114 tests, 3 layers)

Writing new tests

Knowledge Base (RAG)

How it works

Setting up the knowledge base

Adding your own documents

Search quality

Docker

Build and run

Docker architecture

Claude Desktop with Docker

Claude Desktop Setup

macOS

Windows

Verifying it works

MCP Inspector

Security

What must never pass through this server

Troubleshooting

ModuleNotFoundError: No module named 'fastmcp'

search_jpos returns "Knowledge base not initialized"

Claude Desktop doesn't show tools

Tests fail with import errors

print() broke the stdio transport

Timeout errors on search_jpos

Roadmap

Contributing

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

`ModuleNotFoundError: No module named 'fastmcp'`

`search_jpos` returns "Knowledge base not initialized"

`print()` broke the stdio transport

Timeout errors on `search_jpos`