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

Related MCP server: AgentPay

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

Payment Hubs

Services

System

Resources

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

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

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):

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