Financial Portfolios AI MCP Server
README.md
# Financial Portfolios AI Model Context Protocol (MCP) Server
[](https://modelcontextprotocol.io)
[](https://claude.com/docs/connectors/building)
[](https://platform.openai.com/docs/actions)
[](https://cloud.google.com/vertex-ai)
[](https://www.python.org/downloads/)
[](LICENSE)
Official Model Context Protocol (MCP) server for [Financial Portfolios AI](https://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`](openapi.yaml).
- **Local MCP (Claude Desktop, Gemini CLI, Cursor, Windsurf):** Runs via standard I/O (`stdio`).
---
## Authentication
1. Visit [financial-portfolios.ai](https://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](https://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](#authentication)).
- **Directory Manifest:** Uses [`claude_connector.json`](claude_connector.json).
- **Claude Desktop Config:** See [`clients/mcp_clients.dev.json`](clients/mcp_clients.dev.json) or [`clients/mcp_clients.prod.json`](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](https://chatgpt.com/gpts/editor) -> **Configure** -> **Actions** -> **Create new action**.
2. Paste the contents of [`openapi.yaml`](openapi.yaml).
3. 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>/mcp` with [`chatgpt_manifest.json`](chatgpt_manifest.json).
---
### 3. Google Gemini & Google Cloud Vertex AI
- **Gemini CLI extension** (the supported path): [`gemini-extension.json`](gemini-extension.json)
with [`GEMINI.md`](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:**
```bash
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`):**
```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`):**
See [`clients/mcp_clients.dev.json`](clients/mcp_clients.dev.json) or [`clients/mcp_clients.prod.json`](clients/mcp_clients.prod.json).
---
## 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
```bash
# 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](#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:
```bash
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:
```bash
# 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](docs/CI.md) - it needs an `SDK_DEPLOY_KEY` secret, because the SDK
is a separate repository.
---
## Local Development & Testing
```bash
# 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.
```bash
# 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.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessOutdated data