MCP Research

A TypeScript monorepo containing a read-only financial API and stateless remote MCP server on Cloudflare. Both transports share the same user-scoped application services backed by Cloudflare D1 and Drizzle ORM. The MCP endpoint supports development bearer tokens and an OAuth 2.1 authorization-code flow with PKCE.

Requirements and setup

• Node.js 24 LTS or newer
• pnpm 10.33.0 (pinned through packageManager)
• A Cloudflare account only when deploying

corepack enable
pnpm install
cp apps/finance-api/.dev.vars.example apps/finance-api/.dev.vars
pnpm --filter @mcp-research/finance-api db:migrate:local
pnpm --filter @mcp-research/finance-api db:seed:local
pnpm dev

The local Worker is then available at the URL printed by Wrangler. GET / is a public health check. Financial endpoints require one of the development-only bearer tokens configured in .dev.vars:

curl -H 'Authorization: Bearer dev-alice' \
  'http://localhost:8787/v1/transactions?from=2026-06-01&to=2026-06-30'

The development authentication mechanism refuses all requests unless ENVIRONMENT=development. It must be replaced with the OAuth authorization context before production deployment.

MCP

The Streamable HTTP MCP endpoint is available at:

POST /mcp

It exposes four read-only tools:

get_financial_overview
list_transactions
get_transaction
summarize_cashflow

For a quick local connection, start the Worker and run MCP Inspector:

pnpm dev
npx @modelcontextprotocol/inspector@latest

Connect the Inspector to http://localhost:8787/mcp. The OAuth flow signs in through GitHub, verifies the immutable numeric GitHub user ID against an owner allowlist, and then displays the MCP consent screen. Direct development protocol requests can instead use Authorization: Bearer dev-alice or Authorization: Bearer dev-bob.

The MCP server is stateless: every request creates a new MCP server and transport. Tool handlers call the same application services as the Hono routes and never make loopback HTTP requests.

OAuth

The Worker provides the MCP OAuth endpoints and discovery documents:

GET|POST /authorize
GET      /callback
POST     /token
POST     /register
GET      /.well-known/oauth-protected-resource
GET      /.well-known/oauth-authorization-server

Only the finance:read scope is supported. OAuth grants carry an internal userId; MCP tools derive ownership from that grant and never accept a user ID as input. The verified GitHub identity is mapped to the pre-existing financial owner through the identity_links table.

Create a GitHub OAuth App with http://localhost:8787/callback as its local callback URL, then configure these ignored .dev.vars values:

FINANCE_OWNER_USER_ID=usr_alice
GITHUB_ALLOWED_USER_ID=<immutable numeric GitHub user ID>
GITHUB_CLIENT_ID=<OAuth App client ID>
GITHUB_CLIENT_SECRET=<OAuth App client secret>

The authenticated GitHub ID must exactly match GITHUB_ALLOWED_USER_ID. On the first successful owner login, the server may create that one identity link to FINANCE_OWNER_USER_ID; it never creates financial users. All other valid GitHub accounts receive 403. Use a separate GitHub OAuth App with the deployed HTTPS callback URL for production, and store its client secret with wrangler secret put rather than in source control.

For a remote deployment, create a KV namespace for OAuth token and grant storage and replace the placeholder OAUTH_KV ID in apps/finance-api/wrangler.jsonc:

pnpm --filter @mcp-research/finance-api exec wrangler kv namespace create OAUTH_KV

If a browser-based MCP client uses a different origin, add it to the comma-separated MCP_ALLOWED_ORIGINS binding. Requests without an Origin header are supported; untrusted supplied origins receive 403.

API

All financial routes derive the user ID from the authenticated principal. No route accepts a caller-supplied user ID.

GET /v1/me
GET /v1/accounts
GET /v1/accounts/:accountId
GET /v1/balances
GET /v1/transactions?account_id=&from=&to=&cursor=&limit=
GET /v1/transactions/:transactionId
GET /v1/analytics/cashflow?from=&to=

Amounts are integers in minor currency units. Transaction listings use an opaque cursor and default to 50 results, with a maximum of 100.

Database

The Drizzle schema lives in apps/finance-api/src/db/schema.ts. After changing it, generate a migration with:

pnpm --filter @mcp-research/finance-api db:generate

The committed D1 identifier is a local placeholder. Before remote deployment, create the database and replace database_id in apps/finance-api/wrangler.jsonc with the returned ID:

pnpm --filter @mcp-research/finance-api exec wrangler d1 create finance-api-db
pnpm --filter @mcp-research/finance-api exec wrangler d1 migrations apply finance-api-db --remote
pnpm --filter @mcp-research/finance-api exec wrangler d1 execute finance-api-db --remote --file=./seed/production-bootstrap.sql

The deterministic development seed is for local development and integration tests only. The production bootstrap inserts the configured owner without adding sample financial data; keep its user ID aligned with FINANCE_OWNER_USER_ID.

Quality checks

pnpm test
pnpm format:check
pnpm lint
pnpm typecheck
pnpm build

The Worker test suite runs inside Cloudflare's Workers runtime and applies the D1 migrations to isolated local storage.

GET / returns:

{ "service": "mcp-research-finance-api", "status": "ok" }

Run pnpm --filter @mcp-research/finance-api types after changing wrangler.jsonc bindings; Wrangler generates apps/finance-api/worker-configuration.d.ts, which TypeScript consumes through the API tsconfig. Deploy with pnpm --filter @mcp-research/finance-api run deploy after configuring a real D1 database and production authentication.

Structure

apps/finance-api/src/         Hono routes, MCP tools, OAuth, services, repositories, and schema
apps/finance-api/migrations/  generated D1 migrations
apps/finance-api/seed/        deterministic development data
apps/finance-api/test/        Worker-runtime integration tests
tsconfig.base.json            shared strict TypeScript settings
turbo.json                    workspace task graph

The architecture is deliberately one Worker. /v1 and /mcp are transport adapters over shared finance services. Separate Workers or applications should be introduced only when operational or security boundaries justify them.