Monexa

Monexa MCP server

Remote Model Context Protocol server for Monexa, served over Streamable HTTP at https://mcp.monexa.world/mcp. It lets AI assistants read and manage a user's records, categories, payment methods, recurring expenses, trend reports and settings.

This README is for developers and self-hosters. To connect an assistant, see the user guide. The tools are listed in TOOLS.md. Released under the MIT license.

How it works

1. An AI app connects with a Monexa OAuth access token (mnx_at_…, obtained through the OAuth flow the backend serves) or a personal access token (mnx_pat_…) in Authorization: Bearer.
2. The server exchanges the bearer at the backend (RFC 8693, POST /oauth/token, authenticated as the MCP client) for a short-lived delegated JWT. Successful exchanges are cached in memory, keyed by a hash of the token, for at most 4 minutes, and tokens the backend rejects are answered from memory for 30 seconds.
3. Each tool call runs with that JWT against the Monexa REST API (MONEXA_API_URL). The backend only lets delegated tokens reach an allowlist of routes (internal/middlewares/delegated_access.go) and checks the monexa.read / monexa.write scope.
4. The server advertises the backend as its authorization server through protected resource metadata, so OAuth clients discover where to sign in. It mirrors the backend's metadata document, fetched at startup.
5. The server is stateless and keeps no user data. Every request builds its own MCP server instance.

Environment

Set these on the service. The server refuses to start with a clear message when one is missing or malformed.

The backend side of the same setup is OAUTH_ISSUER_URL, MCP_RESOURCE_URL, MCP_CLIENT_ID and MCP_CLIENT_SECRET, optionally OAUTH_ACCESS_TOKEN_TTL (default 1h) and OAUTH_REFRESH_TOKEN_TTL (default 2160h). The backend needs all four or none, and serves no OAuth routes without them. Deployment details are in docs/DEPLOYMENT.md.

Routes

Until the backend's metadata has loaded, every route except /healthz answers 503 with Retry-After. At startup the server fetches ${MONEXA_API_URL}/.well-known/oauth-authorization-server up to 30 times, 2 seconds apart, and exits with code 1 if it never succeeds or if the issuer differs from MONEXA_OAUTH_ISSUER. A backend outage or a rejected client secret reaches clients as 503, never 401, so they do not fall into a re-authentication loop.

Local development

Requires Node 22 and a running backend with OAuth enabled. Start the backend with

OAUTH_ISSUER_URL=http://localhost:9000

MCP_RESOURCE_URL=http://localhost:3001/mcp MCP_CLIENT_ID=monexa-mcp MCP_CLIENT_SECRET=

in its environment, then run the MCP server with the same client credentials. npm run dev loads mcp-server/.env when it exists (git-ignored), so put them there:

PORT=3001

MCP_PUBLIC_URL=http://localhost:3001 MONEXA_OAUTH_ISSUER=http://localhost:9000 MONEXA_API_URL=http://localhost:9000 MCP_CLIENT_ID=monexa-mcp MCP_CLIENT_SECRET=

cd mcp-server

npm install npm run dev

Point the MCP Inspector (npx @modelcontextprotocol/inspector) at http://localhost:3001/mcp and sign in through OAuth, or paste a personal access token created in the web app under Settings, Connected apps.

Scripts

The drift guard

npm run check exits 1 with readable messages unless all of these hold:

• Every route in ../docs/api-routes.json (the backend's route inventory, written by go run ./cmd/routes -write) is covered by exactly one tool's covers list or listed in src/tools/excluded.ts with a reason, and every covers or excluded entry exists in the inventory.
• Every route a tool covers is marked "delegated": true in the inventory, which means the backend allowlist in internal/middlewares/delegated_access.go lets connected apps call it.
• Tool names are unique snake_case of at most 64 characters, and each tool has a title and the four annotation hints, with openWorldHint: false.
• Tools with readOnlyHint: true cover only GET routes.
• TOOLS.md equals what npm run docs generates.
• server.json has the same version as package.json and a description of at most 100 characters.

When the backend gains a route or its delegated allowlist changes, go run ./cmd/routes -check fails first. Run it with -write, then add a tool that covers the route or an entry in excluded.ts, run npm run docs, and commit the results together.

Tools

22 tools cover 24 of the backend's 65 API routes; the other 41 are intentionally excluded, such as sign-in, session and account-security routes, OAuth endpoints, legal documents, data export and trend report editing (see src/tools/excluded.ts and the end of TOOLS.md). Tool names are snake_case, input names are camelCase (for example includeDetails), and inputs are validated with zod before any API call. Every tool declares title, readOnlyHint, destructiveHint, idempotentHint and openWorldHint: false, and returns both structuredContent and a JSON text block.

Operations

• Logging. One JSON line per /mcp request with the HTTP and JSON-RPC method, tool name, status, duration in milliseconds and the OAuth client ID. Tokens and tool arguments are never logged.
• Shutdown. On SIGTERM or SIGINT the server stops accepting connections and lets in-flight requests finish. It exits 0 when they are done and forces exit 1 after 8 seconds.
• Container. The Dockerfile builds a node:22-alpine image that runs as a non-root user and probes /healthz; the start period allows for the metadata retries.

Versioning and releases

The version in package.json follows SemVer; server.json must carry the same version, and npm run check enforces it.

• Major: a tool is removed or renamed, or a tool's schema changes incompatibly.
• Minor: a new tool or a new optional parameter.
• Patch: fixes with no schema change.

Record changes under ## [Unreleased] in CHANGELOG.md (Keep a Changelog) and move them under the new version heading when releasing. Set a new tool's since to the version that introduces it.

To release, bump package.json, server.json and the changelog, merge to master, then push the tag mcp-vX.Y.Z (for example git tag mcp-v2.0.0 && git push origin mcp-v2.0.0). CI pushes the image ghcr.io/emilijan-koteski/monexa-mcp:vX.Y.Z and publishes server.json to the official MCP Registry as io.github.emilijan-koteski/monexa. Merging to master deploys the sha- image to production independently of tags.

Support

Questions and bug reports: emilijankoteski@pm.me or an issue on GitHub.