Protocol Wealth · Open Source

Connect to the MCP server

Nexus Core speaks the Model Context Protocol, so any MCP-compatible AI client can call its public demo tools. Remote clients may complete transparent OAuth with no login. You can use the hosted server or run your own.

Option A — Use the hosted server (no install)

The server is live at https://nexusmcp.site/mcp/ (MCP over HTTP / Streamable HTTP). Clients that support remote MCP servers can add that URL directly.

Claude.ai (web & desktop app)

Settings → Connectors → Add custom connector, paste the URL above, and add it. Claude completes a transparent authorization automatically — there is no account or login (nexus-core is public); you may briefly see an authorize step that approves itself. No OAuth Client ID needs to be entered.

Claude Code

Claude Code speaks remote MCP over HTTP. Add the hosted server with one command:

claude mcp add --transport http nexus-core https://nexusmcp.site/mcp/

or commit a .mcp.json to your project root so the whole team picks it up:

{
  "mcpServers": {
    "nexus-core": {
      "type": "http",
      "url": "https://nexusmcp.site/mcp/"
    }
  }
}

Run /mcp inside Claude Code to confirm the connection and see the tool list.

Claude Desktop

Claude Desktop connects to local processes, so bridge to the hosted URL with mcp-remote. Add this to your claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "nexus-core": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://nexusmcp.site/mcp/"]
    }
  }
}

Config file location — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json. Restart Claude Desktop, then look for the nexus-core tools in the tools menu.

Other clients (Cursor, Cline, custom)

Most clients that support remote MCP servers accept the URL directly — point them at https://nexusmcp.site/mcp/ with the HTTP / Streamable-HTTP transport. Any MCP-compatible AI client (Claude, GPT, Gemini), or an agent platform such as SmythOS, can register this read-only endpoint the same way — no account or API key.

Option B — Run it locally (stdio)

Install from source (Python 3.12+), then run the stdio server:

pip install "nexus-core[mcp] @ git+https://github.com/Protocol-Wealth/nexus-core.git"

# optional: a free FRED API key sharpens the macro signals
export FRED_API_KEY=your_key

nexus-core mcp        # MCP server over stdio

Point Claude Desktop at the local command:

{
  "mcpServers": {
    "nexus-core": {
      "command": "nexus-core",
      "args": ["mcp"]
    }
  }
}

Full-profile tools

Everything is read-only, public, and educational — no side effects, no advice. The exact, always-current tool list is what your client shows after connecting (or call tools/list).

Try it — example prompts

Once connected, just ask in plain language; the client picks the tool and fills the arguments. A few prompts that exercise the regime engine and the planning tools end to end:

• “What macro regime are we in right now, and which signals are driving it?”
• “Score AAPL on the EMF durability framework and explain each of the eight checks.”
• “Run a Monte Carlo decumulation: age 62, retiring at 65, $1.2M traditional + $300k Roth, 60/40 then 80/20, $120k annual spend at 2.5% COLA, Social Security $42k from 67. Use the EMF-regime return model and report the probability of success.”
• “Pull the current capital-market assumptions, then re-run that plan with those real assumptions and compare the success probability.”
• “Build a tax-aware, RMD-first withdrawal plan for a $120k need at age 73 across those accounts.”
• “Given the current macro regime, which covered-call strike should I write on 5 BTC over the next 45 days? Show the regime tilt and the coin yield.”
• “Rank the live BTC OTM calls by annualized covered-call yield, and show the IV term structure so I can see which expiry pays richest.”
• “Illustrate a protective collar on 5 ETH with a 20%-OTM put floor and a 25%-OTM call cap, and stress the book for a ±30% spot move.”

Verify the connection

Inspect the server interactively with the official MCP Inspector:

# hosted
npx @modelcontextprotocol/inspector https://nexusmcp.site/mcp/

# local
npx @modelcontextprotocol/inspector nexus-core mcp

Connecting pwplan-core to nexus-core

pwplan-core is the open-source, browser-based financial-planning shell. It runs entirely in the browser and calls nexus-core's planning engine directly over HTTP — no SDK. These are plain REST endpoints (distinct from the MCP transport above). Production callers can send a Nexus service API key through the REST/JSON boundary when restricted mode is enabled.

The handshake

Call GET /api/planning/tools first — it returns the contract version and the available tool ids, so the client can confirm compatibility before sending any work:

GET https://nexusmcp.site/api/planning/tools
→ { "contractVersion": "0.1.0", "tools": [ ... ] }

The wire contract is contractVersion 0.1.0 — every successful tool response echoes it, and the client rejects a mismatch.

The planning tools

Invoke a tool with POST /api/planning/tools/{tool_id} and a JSON body. Legacy /mcp/tools aliases remain for older clients:

• monte_carlo_decumulation — primary retirement decumulation simulation, including optional same-seed LTC-shock impact
• solve_goal — solve one planning variable to a target success probability
• analyze_goals — goal-funding status + shared-pool priority allocation
• project_cash_flow — deterministic year-by-year cash-flow and net-worth projection, including optional LTC shock expense rows
• cashflow_planning_bridge — derived monthly close values into planning assumptions
• cash_reserve_analysis — cash reserve coverage and funding status
• budget_pacing_projection — month-end budget pace from aggregate spending
• education_funding — education cost FV and savings-need solver
• education_vehicle_rules — reference 529 / Coverdell / UGMA-UTMA rule table
• income_layering — stacked retirement income timeline with Social Security, pensions/annuities, RMDs, tax-aware withdrawals, optional state-tax layers, and optional spouse/survivor modeling
• glide_path — equity weight by age across the horizon
• tax_aware_withdrawal — RMD-first, tax-efficient withdrawal sequencing with optional birthYear and state/residency policy
• correlation_matrix — real-data return correlation across asset classes
• capital_market_assumptions — forward return / volatility / correlation assumptions
• historical_blend — historical index-blend returns, trailing windows, growth-of-dollar, and sigma bands
• regime_return_generator — live regime + transition matrix for path generation
• roth_conversion — convert-now vs. leave-pre-tax after-tax comparison + breakeven rate
• sequence_of_returns_stress — ordering effect on a fixed return set (worst/best/as-given)
• rmd — required minimum distribution (IRS Uniform Lifetime Table; optional birthYear policy)
• tax_bracket_headroom — marginal bracket + room before the next rate (Roth-fill)
• inherited_ira_analysis — inherited IRA 10-year strategy comparison and EDB carve-out notes; not a separate annual RMD compliance calculator
• social_security_claiming — benefit by claim age 62–70 + breakeven ages
• regime_conditioned_swr — base safe withdrawal rate adjusted for the live regime
• portfolio_xray — regime-aware structural diagnostics (concentration, tax-location, regime sensitivity)
• optimize_allocation — optimizer-driven target asset-class weights
• risk_profile_score — fixed-question risk questionnaire → optimizer-compatible riskProfile
• fire — FIRE / Coast-FIRE calculator
• risk_metrics — annualized return/volatility, Sharpe, Sortino, drawdown, VaR/CVaR
• performance_analysis — TWR, MWR/XIRR, fee drag, and benchmark-relative return math
• rebalance — target-vs-current drift and self-financing trade list
• irmaa_headroom — projected Medicare IRMAA headroom
• analyze_roth_conversion — composite Roth conversion analysis under tax + IRMAA ceilings
• sequence_conversions — multi-year Roth conversion sequencing
• build_planning_report — ordered, render-ready envelope from de-identified planning outputs; optional PW Wealth Roadmap preset

A worked request — the primary tool

monte_carlo_decumulation over a de-identified portfolio. The response echoes contractVersion and carries successProbability with a Wilson interval, a terminalValues percentile map, medianBalanceByYear, depletionStats, sticky depletionCurve, conditionalShortfall, firstDecadeReturnVsOutcome deciles, and a regimePathSummary for the regime-aware models:

curl -s https://nexusmcp.site/mcp/tools/monte_carlo_decumulation \
  -H 'content-type: application/json' \
  -d '{
    "contractVersion": "0.1.0",
    "currentAge": 62, "retirementAge": 65, "horizonAge": 95,
    "accounts": [
      {"type": "traditional", "balance": 1200000,
       "allocation": {"us_equity": 0.6, "us_bonds": 0.4}}
    ],
    "assetClasses": [
      {"id": "us_equity", "label": "US Equity",
       "expectedReturn": 0.07, "volatility": 0.16, "lambda": 0.35},
      {"id": "us_bonds", "label": "US Bonds",
       "expectedReturn": 0.03, "volatility": 0.05, "lambda": 0.1}
    ],
    "annualSpend": 120000, "spendColaRate": 0.025,
    "guaranteedIncome": [
      {"label": "Social Security", "annualAmount": 42000,
       "startAge": 67, "colaRate": 0.02}
    ],
    "spendSchedule": [
      {"mode": "delta", "startAge": 91, "endAge": 95, "amount": 70000}
    ],
    "filingStatus": "married_joint", "returnModel": "emf_regime", "paths": 10000
  }'