Skip to main content
Glama
Financial Portfolios AI MCP Server

Financial Portfolios AI MCP Server

Financial Portfolios AI Model Context Protocol (MCP) Server

MCP Standard Claude Connectors OpenAI Compatible Google Vertex AI Python 3.10+ License: MIT

Official Model Context Protocol (MCP) server for Financial Portfolios AI.

This MCP server connects Claude, ChatGPT, and Google Gemini directly to institutional-grade quantitative portfolio strategies, target asset allocation snapshots, portfolio rebalancing engine, and proprietary quantitative research.


Universal Architecture Overview

 ┌────────────────────────────────────────────────────────────────────────┐
 │        AI Ecosystem: Claude · ChatGPT · Gemini · Cursor · Windsurf     │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                     MCP / OpenAPI Protocols (HTTP / stdio)
                                     │
 ┌───────────────────────────────────▼────────────────────────────────────┐
 │           Financial Portfolios AI MCP Server (Google Cloud Run)        │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                            REST & WebSocket API
                                     │
 ┌───────────────────────────────────▼────────────────────────────────────┐
 │         Customer Portal Backend (https://financial-portfolios.ai)      │
 └────────────────────────────────────────────────────────────────────────┘
  • Remote MCP (Claude Connectors & ChatGPT Apps): Streamable HTTP (/mcp) and Server-Sent Events (/sse), hosted on Google Cloud Run.

  • OpenAPI REST Actions (ChatGPT Custom GPTs & Google Vertex AI): Defined via openapi.yaml.

  • Local MCP (Claude Desktop, Gemini CLI, Cursor, Windsurf): Runs via standard I/O (stdio).


Related MCP server: FinzData

Authentication

  1. Visit financial-portfolios.ai and sign in using Google Social Login (or email credentials).

  2. Go to Settings > API Tokens (or financial-portfolios.ai/api-access).

  3. Click Generate API Token.

  4. Copy your token (starts with aqat_v1_...).


Multi-Platform Ecosystem Setup

1. Claude AI (claude.ai Connectors & Claude Desktop)

  • Claude Web Custom Connector:

    1. Go to Customize > Connectors -> Add custom connector.

    2. Enter the server URL https://financial-portfolios.ai/mcp and sign in when prompted. Authentication is OAuth 2.1 - there is no API key to paste. A tokenless request is answered with a 401 + WWW-Authenticate: Bearer resource_metadata=... (RFC 9728), which is what starts the sign-in flow.

    3. Command-line clients (Claude Code) do not run that flow: they pass a personal token as an X-API-Key header instead (see Authentication).

  • Directory Manifest: Uses claude_connector.json.

  • Claude Desktop Config: See clients/mcp_clients.dev.json or clients/mcp_clients.prod.json for claude_desktop_config.json - pick the deployment you are installing against.


2. OpenAI ChatGPT (Custom GPTs & MCP Apps)

  • ChatGPT Custom GPT Actions (GPT Store):

    1. Open ChatGPT GPT Builder -> Configure -> Actions -> Create new action.

    2. Paste the contents of openapi.yaml.

    3. Under Authentication, choose API Key, Auth Type: Custom, Header Name: X-API-Key.

  • ChatGPT MCP Apps (Enterprise & Workspace):


3. Google Gemini & Google Cloud Vertex AI

  • Gemini CLI extension (the supported path): gemini-extension.json with GEMINI.md as its context file. Installed from a public repository with gemini extensions install <repo-url>, then gemini extensions config financial-portfolios-ai to set the API token. Gemini CLI renders no MCP Apps, so the app tools that only open a UI are excluded and the rest answer as JSON.

  • Gemini CLI, configured by hand:

    gemini mcp add -t http fpai https://<your-domain>/mcp -H "X-API-Key: $FINANCIAL_PORTFOLIOS_API_TOKEN"

4. Developer IDEs (Cursor & Windsurf)


Capabilities Reference

🛠️ Tools

Tool Name

Description

Arguments

open_portfolio_explorer

Interactive (MCP App). Portfolio dropdown, sortable holdings, sector and concentration charts, and changes over time, rendered inline in Claude.

portfolio_code (optional)

list_portfolios

List every active quantitative portfolio, each marked access = subscribed or public_delayed.

api_token (optional)

get_portfolio_allocation

Retrieve a target allocation snapshot: the latest book when subscribed, otherwise the public book delayed ~45 days.

portfolio_code, as_of (optional), api_token (optional)

get_portfolio_history

Retrieve historical allocation timeline for up to 365 days (delayed entries only for non-subscribers).

portfolio_code, days (1-365), api_token (optional)

rebalance_portfolio

Calculate BUY/SELL rebalancing orders to match target allocation given current user holdings. Requires an active subscription.

portfolio_code, holdings (JSON list or CSV), as_of (optional)

get_rebalance_template

Download sample holdings CSV template and formatting instructions.

api_token (optional)

list_blog_posts

Search and list published research articles, macro updates, and commentaries.

page, page_size, search (optional)

get_blog_post

Read full content of a published research article by slug.

slug, api_token (optional)

get_token_info

Inspect API token metadata, usage rate limits, and subscription status.

api_token (optional)

Access levels

Portfolio reads serve one of two books, and every response says which via access, delayed, as_of and lag_days:

subscribed

public_delayed

Holdings

latest book

dated <= today - 45 days (PUBLIC_HOLDINGS_LAG_DAYS)

Position fields

ticker, weight, sector, expected return, expected volatility

ticker, weight, sector only

equity_exposure / cash_allocation / effective_n

populated

null

rebalance_portfolio

allowed

403 - subscription required

A portfolio code that is not an active public product returns 404, deliberately indistinguishable from an unknown code.

📦 Resources

URI

Name

Description

portfolios://catalog

Portfolio Catalog

Live catalog of all available quantitative portfolios.

portfolios://{portfolio_code}/allocation

Portfolio Allocation

Dynamic resource for current allocation of any portfolio.

research://posts/latest

Latest Research

Most recent quantitative market research publications.

💡 Prompts

Ready-made starters Claude lists in the connector. Portfolio-code inputs are optional - left blank, the prompt uses the portfolios you subscribe to - and autocomplete from your live portfolio list.

Prompt

Title

Description

Inputs

my_portfolios

My portfolios at a glance

See which model portfolios you subscribe to and what each one holds right now, plus the other portfolios available on a delayed basis.

—

access_help

My access and subscription

Explains what your account can see: live vs 45-day-delayed holdings, which portfolios you subscribe to, and what needs a subscription.

—

portfolio_review

Review a model portfolio

In-depth look at one model portfolio: holdings and weights, sector mix, concentration, and equity vs cash.

portfolio_code (optional)

portfolio_changes

What changed in a portfolio

Shows how a model portfolio's holdings changed over a period: positions added, removed, and the biggest weight shifts.

portfolio_code (optional), days (optional)

compare_portfolios

Compare model portfolios

Side-by-side comparison of the model portfolios: risk level, holdings, sector mix, concentration, and overlap.

portfolio_codes (optional)

find_holding

Which portfolios hold a stock

Look up a stock across the model portfolios: which ones hold it, at what weight, and in which sector.

ticker

portfolio_report

Interactive portfolio report

Builds an interactive report for a model portfolio: sortable holdings, sector and concentration charts, and recent changes, as a shareable page.

portfolio_code (optional), days (optional)

rebalance_advisor

Align my holdings to a model

Walks you through comparing your own holdings with a model portfolio and calculates the share differences. Requires a subscription to that portfolio.

portfolio_code (optional)

market_research_digest

Research digest

Summarises the latest research articles and market commentary, optionally on one topic.

topic (optional)


Google Cloud Run Deployment

# 1. Build and push container with Cloud Build
gcloud builds submit --config=cloudbuild.yaml --substitutions=_ENV=dev   # or _ENV=prod

# 2. Deploy to Cloud Run
gcloud run deploy financial-portfolios-ai-mcp \
  --image gcr.io/<YOUR_PROJECT_ID>/financial-portfolios-ai-mcp:latest \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated \
  --set-env-vars FINANCIAL_PORTFOLIOS_ENV=dev   # or prod

The target is always chosen at deploy or run time. Nothing in this repository defaults to dev or prod: without FINANCIAL_PORTFOLIOS_ENV (or an explicit FINANCIAL_PORTFOLIOS_BASE_URL) the server refuses to start, and cloudbuild.yaml refuses to build without _ENV.

Health Endpoints

  • GET / - Root status, version, and endpoints metadata

  • GET /healthz - Health and readiness check

  • GET /livez - Kubernetes/Cloud Run liveness probe

  • POST /mcp - Streamable HTTP MCP endpoint

  • GET /sse - Server-Sent Events MCP endpoint

  • GET /mcp/assets/{filename} - Public brand icons (icon-16|32|48|64|128|192|256|512.png, favicon.ico)

  • GET /mcp/manifests/{filename} - Provider manifest rendered for the requesting origin

  • GET /favicon.ico - Favicon


Branding & Icons

The server ships its logo so Claude, ChatGPT, Gemini and IDE clients render it next to the connector and its tool calls:

  • In the protocol - initialize returns serverInfo.icons (MCP Implementation.icons, spec revision 2025-11-25). The first entry is an inline 48x48 data: URI, so the icon also appears for local stdio clients with no HTTP server to fetch from; 192x192 and 512x512 follow as absolute HTTPS URLs.

  • Over HTTP - the PNG/ICO set is served unauthenticated from /mcp/assets/ with a one-week immutable cache header. It sits under /mcp because that is the prefix the portal load balancer routes to this service; top-level /assets/* belongs to the portal backend's own assets router, so an icon URL there would never reach us. The OAuth challenge explicitly exempts /mcp/assets and /mcp/manifests so directories can fetch them with no credential.

  • In the manifests - claude_connector.json and chatgpt_manifest.json point their icon_url / logo_url at the same files, through the ${PUBLIC_ORIGIN} placeholder (see Manifests).

Sources live in src/financial_portfolios_ai_mcp/assets/ and ship inside the wheel.

No environment hostname is hardcoded. The absolute URLs resolve in this order:

  1. the origin the request arrived on (X-Forwarded-Proto / X-Forwarded-Host, set by the load balancer and Cloud Run) - so / always advertises the hostname the caller used;

  2. MCP_PUBLIC_BASE_URL, for the initialize handshake, which has no request origin to read (set it when the MCP service answers on its own hostname rather than through the portal);

  3. MCP_PUBLIC_URL with the transport path stripped.

A dev deployment therefore advertises https://dev.financial-portfolios.ai/assets/... purely from its deploy substitution:

gcloud builds submit --config cloudbuild.yaml --substitutions=_ENV=dev

Manifests

The three provider manifests are templates, not environment-specific files: every absolute URL in them is written as ${PUBLIC_ORIGIN}/..., so one document per provider serves prod, dev and anything else. Nothing in the repo hardcodes a deployment hostname.

Get a submittable manifest either way:

# offline, for directory submission
python scripts/render_manifests.py --env prod        # -> build/manifests/prod/
python scripts/render_manifests.py --env dev         # -> build/manifests/dev/
python scripts/render_manifests.py --origin https://staging.financial-portfolios.ai

# or from a running deployment, rendered against the origin you reached it on
curl https://dev.financial-portfolios.ai/mcp/manifests/claude_connector.json

GET /mcp/manifests/<name> is the authoritative rendering: it fills in the origin the request arrived on, so the dev deployment always hands out dev URLs and the prod deployment prod URLs, with no build step and nothing to keep in sync. GET / lists the available manifests. A test asserts the committed templates never regain a hardcoded origin, and another asserts the script and the endpoint produce identical documents.


Continuous Integration

Every push and pull request runs lint, the test suite, and a smoke test against the built image. See docs/CI.md - it needs an SDK_DEPLOY_KEY secret, because the SDK is a separate repository.


Local Development & Testing

# 1. Install dependencies
uv sync --all-extras

# 2. Run unit tests
uv run pytest tests/ -v

# 3. Run linter
uv run ruff check .

# 4. Start local development server (Streamable HTTP & SSE on port 8080)
uv run financial-portfolios-ai-mcp http --port 8080 --reload

End-to-end smoke test

scripts/smoke_test.py exercises a running server over Streamable HTTP with the standard library only (no deps): /healthz → initialize → tools/list, and — if you pass an API token — real tools/call round-trips (list_portfolios → get_portfolio_allocation). It also regression-checks that get_portfolio_allocation advertises the words "holdings"/"positions" so that a prompt like "show me my portfolio holdings" actually invokes it.

# Handshake + tools/list + phrasing check (no credentials needed)
python scripts/smoke_test.py

# Full path incl. entitled data (generate a token at the portal /api-access)
python scripts/smoke_test.py --token aqat_v1_xxxxx
# or:  MCP_URL=http://localhost:8090/mcp/ MCP_TOKEN=aqat_v1_xxxxx python scripts/smoke_test.py

Exit code is 0 only if every executed check passes.

Local docker-compose: there is no default target. Run FINANCIAL_PORTFOLIOS_ENV=dev docker compose up -d, or, to point the server at a local portal backend on the shared docker network, create a (gitignored) .env next to docker-compose.yml with FINANCIAL_PORTFOLIOS_BASE_URL=http://aqa-portal-backend:8000 and docker compose up -d.


License

MIT License. Copyright (c) 2026 Financial Portfolios AI Team.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to access and analyze financial data, stock information, company fundamentals, market insights, and 250+ tools across asset classes. Supports flexible hosted or self-hosted deployment with dynamic toolset management.
      558 npm
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Point-in-time market data and backtests for AI agents, 40 tools: 16,000+ US stocks since 2000 incl. delisted, 5,100+ ETFs, ticks, 139 futures markets, options GEX and chains, VIX, 123 indexes, 79 FX pairs, 512 crypto pairs, fundamentals as filed, 13F, COT since 1986, 22,700+ macro series with every vintage, Global Macro Pulse, congressional trades. Deflated-Sharpe backtests. No key to start.
      11
      256 PyPI
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to access and analyze stocks, ETFs, crypto, forex, commodities, economics, company fundamentals, and market insights through 250+ financial data tools. Supports dynamic toolset loading and multiple deployment modes for flexible integration.
      558 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables ChatGPT, Claude, Cursor and other MCP clients to read a user's real crypto portfolio data — holdings, movement history, FIFO cost basis and P&L, fees, income, risk metrics and target-allocation drift — across connected exchanges and on-chain wallets via read-only OAuth access. An optional propose-only tool parks changes for human approval in the browser rather than writing anything directly.
      1
      MIT