finpay-mcp-server

An MCP (Model Context Protocol) server that exposes a fictional payment domain as tools, resources, and prompt templates. Connect Claude Desktop (or any MCP client) and reason over the FinPay platform — transactions, payment hubs, microservices, and system health.

Built with TypeScript + Node.js using the official @modelcontextprotocol/sdk.

---

What it demonstrates

• Full MCP server implementation: 8 tools, 2 resources, 2 prompts
• Production-quality TypeScript with strict type checking throughout
• Tool schema design using zod — every parameter is typed and described
• MCP governance: tool naming conventions, schema versioning, access control patterns
• stdio transport for Claude Desktop; optional HTTP transport for remote clients

---

Quickstart

Prerequisites: Node.js 22+, npm

git clone https://github.com/your-handle/finpay-mcp-server
cd finpay-mcp-server
npm install
npm run build

Connect to Claude Desktop:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "finpay": {
      "command": "node",
      "args": ["/Users/ThanhNguyen/AI_WS/finpay-mcp-server/dist/index.js"]
    }
  }
}

Restart Claude Desktop. The FinPay tools will appear in the tool panel.

Run in development mode (hot reload):

npm run dev

Run with HTTP transport (Streamable HTTP, stateless):

node dist/index.js --transport http --port 3100

To require an API key on the HTTP transport:

MCP_API_KEY=your-secret node dist/index.js --transport http --port 3100

Clients must then send Authorization: Bearer your-secret with every request.

---

Tools

All tools operate on in-memory fixture data — no API keys or external services required (except search_docs).

Transactions

Tool	Description
get_transaction	Look up a transaction by ID (TXN-XXXXXXXXX)
list_transactions	List recent transactions. Filterable by status, hubId, and limit (max 50)

Payment Hubs

Tool	Description
get_payment_hub	Get a hub's details: status, currencies, latency, 24h success rate
list_payment_hubs	List all hubs (GlobalPay, SwiftRoute, MobileFirst, RegionalX)

Services

Tool	Description
explain_service	Describe a microservice: purpose, dependencies, dependents, health
list_services	List all microservices in the FinPay platform

System

Tool	Description
get_system_health	Unified health snapshot: overall status, per-service health, per-hub metrics, active alerts
search_docs	Full-text search via docu-rag API (requires DOCU_RAG_URL env var)

---

Resources

Resources expose read-only data that the LLM can load directly into context.

URI	Content
finpay://services/catalog	JSON catalog of all services with full metadata
finpay://architecture/overview	Markdown system architecture overview

---

Prompts

Prompt templates inject structured system context to guide LLM behaviour.

architecture-review

Loads the full service catalog, hub list, and dependency graph. Asks the model to conduct a structured architecture review.

Optional argument: focus — area to concentrate on (e.g., resilience, scalability, security)

incident-triage

Loads current system health, recent FAILED/DEGRADED transactions, and hub health metrics. Guides the model through a structured incident triage.

Optional argument: transactionId — specific transaction to investigate

---

Configuration

Variable	Default	Description
DOCU_RAG_URL	—	Base URL of the docu-rag API. Enables search_docs tool.
LOG_LEVEL	info	debug | info | warn | error
LOG_FILE	logs/app.log	Path to the log file. Directory is created automatically on startup.
MCP_API_KEY	—	HTTP transport only. If set, all requests must include Authorization: Bearer <value>.

No API keys required for the core 7 tools. The server runs fully without any .env file.

Copy .env.example if you want to enable the optional search_docs tool:

cp .env.example .env
# Set DOCU_RAG_URL=http://localhost:8001

---

Example Interactions

Once connected to Claude Desktop, try:

Show me all FAILED transactions in the last hour.

Which payment hub has the lowest success rate right now?

Explain the dependency chain for hub-adapter-service and tell me what breaks if compliance-service goes down.

Run an architecture review focused on resilience.

Triage the incident for transaction TXN-100000011.

---

Governance

Tool Naming Conventions

• Names are snake_case, verb-first for actions: get_, list_, search_, explain_
• Tool names are a public API — never renamed once published
• Breaking changes (removed/renamed params) require a new tool name (e.g., get_transaction_v2) and a deprecation notice before the old one is removed

Schema Versioning

This server follows semantic versioning (package.json):

Change type	Version bump
New optional parameter or new response field	Patch (0.0.X)
New tool, new resource, new prompt	Minor (0.X.0)
Removed tool, removed required param, renamed tool	Major (X.0.0) only after deprecation period

Access Control

stdio transport inherits OS user permissions. It is suitable for local, trusted use only (Claude Desktop on your own machine).

HTTP transport is intended for hosted deployments. In production, all tool calls should require Authorization: Bearer <token>. The current HTTP transport implementation accepts a --api-key flag to enable simple token validation. Scope-based access control (restricting which tools a given API key can call) is documented in docs/decisions/ADR-001-transport-strategy.md and recommended for any multi-tenant deployment.

All tools in this server are read-only over mock data. In a production server with write access to real systems, each mutating tool would require an explicit capability scope.

---

Development

npm run typecheck   # type-check without building
npm test            # run tests (vitest)
npm run lint        # eslint
npm run build       # compile to dist/

CI runs on every push: type-check → lint → test.

---

Project Structure

src/
├── index.ts                  # Entry point — CLI arg parsing, transport selection
├── server.ts                 # McpServer setup, registers all tools/resources/prompts
├── logger.ts                 # File + stderr logger (writes to logs/app.log)
├── logging-transport.ts      # Transport wrapper — access log per request/response cycle
├── tools/
│   ├── transactions.ts       # get_transaction, list_transactions
│   ├── hubs.ts               # get_payment_hub, list_payment_hubs
│   ├── services.ts           # explain_service, list_services
│   ├── health.ts             # get_system_health
│   └── docs.ts               # search_docs (docu-rag proxy, requires DOCU_RAG_URL)
├── resources/
│   ├── services-catalog.ts   # finpay://services/catalog
│   └── architecture-overview.ts  # finpay://architecture/overview
├── prompts/
│   ├── architecture-review.ts
│   └── incident-triage.ts
└── data/
    ├── transactions.json     # 20 fixture transactions
    ├── hubs.json             # 4 fixture hubs
    └── services.json         # 7 fixture services
logs/                         # Runtime log output (gitignored)
└── app.log
docs/decisions/               # Architecture Decision Records
tests/
└── tools/                    # Unit tests for all tool modules

---

License

MIT