Financial Portfolios AI MCP Server
Supports Google Cloud Vertex AI via an OpenAPI extension/actions definition, allowing portfolio data, allocation history, and rebalancing workflows to be used from Vertex AI.
Provides a Gemini CLI extension for accessing the portfolio tools and research as JSON responses.
Enables ChatGPT Custom GPT Actions and MCP Apps to query portfolio data, retrieve allocations and history, calculate rebalances, and read research through the provided OpenAPI and remote MCP endpoints.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Financial Portfolios AI Model Context Protocol (MCP) Server
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
Visit financial-portfolios.ai and sign in using Google Social Login (or email credentials).
Go to Settings > API Tokens (or financial-portfolios.ai/api-access).
Click Generate API Token.
Copy your token (starts with
aqat_v1_...).
Multi-Platform Ecosystem Setup
1. Claude AI (claude.ai Connectors & Claude Desktop)
Claude Web Custom Connector:
Go to Customize > Connectors -> Add custom connector.
Enter the server URL
https://financial-portfolios.ai/mcpand sign in when prompted. Authentication is OAuth 2.1 - there is no API key to paste. A tokenless request is answered with a401+WWW-Authenticate: Bearer resource_metadata=...(RFC 9728), which is what starts the sign-in flow.Command-line clients (Claude Code) do not run that flow: they pass a personal token as an
X-API-Keyheader instead (see Authentication).
Directory Manifest: Uses
claude_connector.json.Claude Desktop Config: See
clients/mcp_clients.dev.jsonorclients/mcp_clients.prod.jsonforclaude_desktop_config.json- pick the deployment you are installing against.
2. OpenAI ChatGPT (Custom GPTs & MCP Apps)
ChatGPT Custom GPT Actions (GPT Store):
Open ChatGPT GPT Builder -> Configure -> Actions -> Create new action.
Paste the contents of
openapi.yaml.Under Authentication, choose API Key, Auth Type: Custom, Header Name:
X-API-Key.
ChatGPT MCP Apps (Enterprise & Workspace):
Add Remote MCP endpoint
https://<your-cloud-run-domain>/mcpwithchatgpt_manifest.json.
3. Google Gemini & Google Cloud Vertex AI
Gemini CLI extension (the supported path):
gemini-extension.jsonwithGEMINI.mdas its context file. Installed from a public repository withgemini extensions install <repo-url>, thengemini extensions config financial-portfolios-aito 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)
Cursor IDE (
.cursor/mcp.json):{ "mcpServers": { "fpai": { "url": "https://<your-cloud-run-domain>/mcp", "headers": { "X-API-Key": "aqat_v1_your_token_here" } } } }Windsurf IDE (
~/.codeium/windsurf/mcp_config.json): Seeclients/mcp_clients.dev.jsonorclients/mcp_clients.prod.json.
Capabilities Reference
🛠️ Tools
Tool Name | Description | Arguments |
| Interactive (MCP App). Portfolio dropdown, sortable holdings, sector and concentration charts, and changes over time, rendered inline in Claude. |
|
| List every active quantitative portfolio, each marked |
|
| Retrieve a target allocation snapshot: the latest book when subscribed, otherwise the public book delayed ~45 days. |
|
| Retrieve historical allocation timeline for up to 365 days (delayed entries only for non-subscribers). |
|
| Calculate BUY/SELL rebalancing orders to match target allocation given current user holdings. Requires an active subscription. |
|
| Download sample holdings CSV template and formatting instructions. |
|
| Search and list published research articles, macro updates, and commentaries. |
|
| Read full content of a published research article by slug. |
|
| Inspect API token metadata, usage rate limits, and subscription status. |
|
Access levels
Portfolio reads serve one of two books, and every response says which via access, delayed,
as_of and lag_days:
|
| |
Holdings | latest book | dated |
Position fields | ticker, weight, sector, expected return, expected volatility | ticker, weight, sector only |
| populated |
|
| 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 |
| Portfolio Catalog | Live catalog of all available quantitative portfolios. |
| Portfolio Allocation | Dynamic resource for current allocation of any portfolio. |
| 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 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. | — |
| 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. | — |
| Review a model portfolio | In-depth look at one model portfolio: holdings and weights, sector mix, concentration, and equity vs cash. |
|
| What changed in a portfolio | Shows how a model portfolio's holdings changed over a period: positions added, removed, and the biggest weight shifts. |
|
| Compare model portfolios | Side-by-side comparison of the model portfolios: risk level, holdings, sector mix, concentration, and overlap. |
|
| Which portfolios hold a stock | Look up a stock across the model portfolios: which ones hold it, at what weight, and in which sector. |
|
| Interactive portfolio report | Builds an interactive report for a model portfolio: sortable holdings, sector and concentration charts, and recent changes, as a shareable page. |
|
| 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. |
|
| Research digest | Summarises the latest research articles and market commentary, optionally on one topic. |
|
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 prodThe 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 metadataGET /healthz- Health and readiness checkGET /livez- Kubernetes/Cloud Run liveness probePOST /mcp- Streamable HTTP MCP endpointGET /sse- Server-Sent Events MCP endpointGET /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 originGET /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 -
initializereturnsserverInfo.icons(MCPImplementation.icons, spec revision 2025-11-25). The first entry is an inline 48x48data: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/mcpbecause 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/assetsand/mcp/manifestsso directories can fetch them with no credential.In the manifests -
claude_connector.jsonandchatgpt_manifest.jsonpoint theiricon_url/logo_urlat 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:
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;MCP_PUBLIC_BASE_URL, for theinitializehandshake, which has no request origin to read (set it when the MCP service answers on its own hostname rather than through the portal);MCP_PUBLIC_URLwith 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=devManifests
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.jsonGET /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 --reloadEnd-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.pyExit 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).envnext todocker-compose.ymlwithFINANCIAL_PORTFOLIOS_BASE_URL=http://aqa-portal-backend:8000anddocker 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Portfolio analytics + US-equity market research for AI clients. ChatGPT deep-research compat.
Connect your portfolio to Claude, ChatGPT, or Codex to analyze it and make smarter investments.
Unified financial infrastructure connecting AI agents directly to trade live/demo brokerage accounts, Web3 non-custodial wallets, real-time market data across equities, ETFs, crypto, forex, options, DeFi swaps, and prediction markets, institutional research feeds, and algorithmic strategy backtesters.
Connect brokerage accounts to AI assistants: holdings, orders, asset lookup, and approved trading.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmApache 2.0

FinzDataofficial
AlicenseAqualityBmaintenancePoint-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.11256 PyPIMIT- AlicenseNot gradedqualityAmaintenanceEnables 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 npmApache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables 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.1MIT