moolre-mcp (Node.js)

MCP server exposing Moolre's API — accounts, transfers, payments, SMS, WhatsApp — as 24 tools an AI agent can call. This is the Node.js port of the original PHP implementation (mcp_php/mcp.php); behavior is a 1:1 match, verified against it directly.

Built on the official @modelcontextprotocol/sdk for protocol handling (JSON-RPC validation, session management, SSE framing) — Moolre-specific logic (the REST client and 24 tool definitions) is the only custom code.

Requirements

• Node.js 18 or later (uses the built-in fetch; developed and tested on Node 22).

• npm install (pulls in @modelcontextprotocol/sdk).

Related MCP server: M-Pesa MCP Server

Running locally (stdio — for MCP clients like Claude Code, Cursor)

node mcp.js

When run with a plain node mcp.js and no PORT env var, this reads/writes newline-delimited JSON-RPC over stdin/stdout — the shape an MCP client expects when it spawns the server as a subprocess, e.g. "command": "node", "args": ["/path/to/mcp.js"] in the client's MCP config. See CURSOR_SETUP.md / AGENT_SETUP.md for full config examples.

Running as a hosted HTTP server

PORT=3000 node mcp.js

Setting PORT (which most Node hosts — Render, Railway, Fly.io, etc. — inject automatically) switches this to the Streamable HTTP transport: a single endpoint handling

• POST — JSON-RPC messages (responds as plain JSON, or as an SSE-framed event if the client sends Accept: text/event-stream)

• GET — optional standalone SSE stream (used for server-initiated messages; this server has none to push, so it opens and immediately closes the stream — enough to satisfy clients that check for SSE support)

• DELETE — explicit session termination

Session IDs are issued on initialize via the Mcp-Session-Id response header (handled by the SDK's StreamableHTTPServerTransport), and required on every subsequent request via the same header. We keep one transport (and one connected MCP Server instance) per session in an in-memory Map — if you ever run multiple instances behind a load balancer without sticky sessions, session lookups will fail against the wrong instance. For a single hosted instance this isn't a concern.

To force HTTP mode without a PORT (rare), set MCP_TRANSPORT=http instead (defaults to port 3000).

Environment variables

All of these are fallbacks only — if a tool call explicitly supplies headers or accountnumber in its arguments, that always takes precedence over the environment.

The single header Moolre actually receives is always X-API-VASKEY — the two env vars just let the server pick the right value automatically depending on which service (SMS vs WhatsApp) the tool being called talks to.

Project structure

• mcp.js — REST client (callRest), the MCP Server wiring (tools/list / tools/call handlers), and both transports (stdio via StdioServerTransport, HTTP via StreamableHTTPServerTransport + a thin session-routing layer)

• tools.js — the 24 tool schemas and their REST-call configuration (method, path, default type, credential group)

Testing

# stdio
printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node mcp.js

# HTTP
PORT=3000 node mcp.js &
curl -s -i -X POST http://127.0.0.1:3000/ \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Note: the SDK validates requests against the real MCP schema, so initialize needs a proper clientInfo/capabilities payload (real MCP clients already send this) — unlike the earlier hand-rolled version, bare {"params":{}} won't pass validation.