PA MCP Server

MCP server that exposes the Portfolio Advisor (PA) engine as a tool for AI agents. The quantitative engine is included in pa_engine/src, so the project is self-contained and does not depend on folders or data external to the distribution.

Product documentation and limitations: PRODUCT_OVERVIEW.md. Privacy template to be submitted for professional review: PRIVACY_NOTICE_TEMPLATE.md. Pre-release audit outcome: AUDIT_REPORT.md.

What it exposes

The agent first calls schema_input_pa, collects the data, and passes the configuration to valida_input_pa. If valid=true, it calls prepara_simulazione: the client shows a panel with the filled-in parameters and the simulation stays paused. The user can modify the values and must confirm explicitly. The widget freezes the configuration and sends an internal approval identifier to the agent; the agent then calls analisi_completa directly, which includes optimization, expected returns, Monte Carlo, stress tests, and benchmark comparison. The approval expires after 2 hours and is consumed when the full report completes successfully.

If the user provides a list of instruments, the agent passes it to verifica_strumenti and explains each rejection in detail. If the user has no list and asks for suggestions, the agent uses proponi_strumenti, presents ticker, name, exchange, estimated cost, and comment, then waits for explicit confirmation before verification and configuration. No substitution happens automatically.

cost_annual_pct is expressed in percentage points: 0.50 means 0,50% per year. Clients without MCP Apps support can validate and display the draft, but cannot complete the interactive approval flow.

Setup

python3.13 -m venv .venv
./.venv/bin/python -m pip install .

To modify and rebuild the widgets you also need Node.js 20+ and npm ci.

The Portfolio Advisor engine is included in the project in pa_engine/src, so the server is self-contained. For development, you can point to an alternative engine:

export PA_ENGINE_DIR="/percorso/del/motore"   # opzionale, solo sviluppo

Startup

Local (stdio):

./.venv/bin/python -m pa_mcp.server

Streamable HTTP, for remote connectors and MCP Apps testing:

PA_MCP_TRANSPORT=http PA_MCP_PORT=3000 \
  ./.venv/bin/python -m pa_mcp.server

MCP endpoint: http://127.0.0.1:3000/mcp. For web clients it must be exposed temporarily via HTTPS or deployed on a remote host. The local HTTP startup does not enable authentication and must not be published directly to production.

Approvals, reviews, and cache are persistent and shareable (they survive restarts) by enabling a writable state path:

PA_STATE_PATH=/var/lib/pa_mcp/state.db PA_MCP_TRANSPORT=http PA_MCP_PORT=3000 \
  ./.venv/bin/python -m pa_mcp.server

Without PA_STATE_PATH, state stays in memory (the usual behavior for local development and testing).

OAuth (HTTP, before exposing the endpoint)

OAuth 2.1 (scope pa.read) is available via FastMCP OAuthProvider:

PA_OAUTH=1 PA_PUBLIC_BASE_URL=https://pa.example.com \
  PA_MCP_TRANSPORT=http PA_MCP_PORT=3000 ./.venv/bin/python -m pa_mcp.server

If PA_OAUTH is not set, the HTTP server remains without authentication (suitable for development and testing). In production, OAuth tokens should be persisted in the shared store and per-tenant authorization configured.

Infrastructure protection (HTTP)

• PA_RATE_LIMIT_PER_MIN — per-IP token bucket (HTTP 429).

• PA_MAX_BODY_BYTES — request body size limit (HTTP 413).

• PA_ANALYSIS_TIMEOUT_SECONDS — hard deadline for analysis (60s by default; releases the slot and approval).

• PA_ANALYSIS_QUOTA_PER_HOUR — hourly analysis quota per tenant (0 = unlimited); tenant key via PA_TENANT (default anonymous).

Observability (HTTP)

• GET /health/live — liveness.

• GET /health/ready — readiness (503 if not ready; store state).

• GET /metrics — operational counters (no personal data).

Deploy and documents

To publish the connector you will need a stable endpoint (not the tunnel): follow DEPLOY_GUIDE.md (includes Dockerfile). Draft privacy notice and terms are in PRIVACY_NOTICE_DRAFT.md and TERMS_OF_USE_DRAFT.md (to be reviewed).

For clients, the new modules pa_mcp/auth.py, pa_mcp/limits.py, pa_mcp/state.py, pa_mcp/oauth_provider.py, pa_mcp/quotas.py are included in the wheel.

The server communicates over stdio: any MCP client can connect to it. Example configuration for a generic client:

{
  "mcpServers": {
    "pa-engine": {
      "command": "/percorso/pa-mcp-server/.venv/bin/python",
      "args": ["/percorso/pa-mcp-server/server_script.py"],
      "cwd": "/percorso/pa-mcp-server"
    }
  }
}

Testing the tools

Offline test of the contract and approval flow:

./.venv/bin/python -m unittest discover -s tests -p 'test_*.py'
node scripts/test_config_widget_render.js
node scripts/test_widget_render.js

Full self-check with market data:

./.venv/bin/python -m pa_mcp.selfcheck

Runs all tools against a test config with real data (requires network access to Yahoo Finance) and prints the keys of each output.

Note on the engine

The wrapper reuses pa/src from the PA engine. It does not recompute anything: it delegates the full pipeline to the engine and serializes the JSON report produced by export_report_json. If the engine interface changes, update pa_mcp/engine.py.

Bug fix applied to the engine (numpy 2.x)

pa/src/core/stress_test.py: weights.to_numpy(dtype=float) with numpy 2.x returns a read-only array, and target /= target.sum() failed with ValueError: output array is read-only. Fixed with np.array(weights.to_numpy(dtype=float)). Being upstreamed into the engine.

Roadmap

1. Professional financial, tax, privacy, and data license review.

2. Remote deploy with OAuth 2.1, tenant isolation, quotas, and observability.

3. Publication on supported registries after independent security review.

The blocking checklist is in GO_LIVE_CHECKLIST.md.