mcp-fc

MCP server exposing the financecentre MongoDB (stocks, prices, SEC financials, insider trades, 13F funds, congressional trades, macro series, news) to AI agents. Streamable HTTP (stateless), scoped API keys, token-efficient pipe-table output.

Quick start

cp .env.example .env   # set MCP_API_KEYS or MCP_AUTH_DISABLED=true for dev
npm ci
npm run ensure-indexes
npm run dev            # or: npm run build && npm start

Tools (v1, read-only)

search_securities · get_security_snapshot · screen_stocks · get_price_history · get_financials · get_insider_trades · search_funds · get_fund_holdings · get_political_trades · get_macro_series · search_news · get_news_for_geocoding

Write tools (scope write): submit_news_locations

Auth

Two parallel mechanisms on POST /mcp:

• API keys (MCP_API_KEYS) — for Claude Code, curl, n8n: Authorization: Bearer <key>.
• OAuth 2.1 (enabled when MCP_JWT_SECRET is set) — for claude.ai custom connectors (web/desktop/mobile). Login uses finanz-copilot accounts (financecentre.users, read-only); role admin → scopes read write, member → read. JWT access tokens (1 h), rotating refresh tokens (30 d), PKCE + dynamic client registration. OAuth data lives in the mcp-fc database.

GeoNews (map feature)

newsGeo stores one location per news (GeoJSON Point, [lon, lat], WGS84 — MapKit: CLLocationCoordinate2D(latitude: c[1], longitude: c[0])) plus denormalized news fields (title, sourceName, link, image, pubDate, category), a relevance score and an optional pin summary. Agent loop: get_news_for_geocoding (read) → locate + score → submit_news_locations (write scope). Not-locatable news are stored as locatable: false markers.

relevance (0–1, required for located items) rates the event's significance — 0.95+ historic shock (9/11, market crash), 0.8+ major (central-bank surprise, war escalation), 0.6+ notable, 0.3 routine, <0.1 trivial. The app scales pin size/color with it and raises the threshold when zoomed out; indexes {location:2dsphere} and {relevance:-1, pubDate:-1} back both query shapes. REST integration: docs/geonews-restapi-integration.md.

Adding a feature

1. Create src/features/<name>/index.ts exporting a FeatureModule.
2. Add it to allFeatures in src/features/index.ts.
3. Add an integration test in tests/integration/.

Write tools: set requiredScope: 'write' and grant the scope to a key.

Design: docs/superpowers/specs/2026-07-14-mcp-financecentre-design.md Deployment: deploy/DEPLOY.md

Tests

npm test   # unit + integration + e2e (needs local MongoDB with financecentre)