Practical notes: How Family Offices Can Use Claude + FMP MCP to Detect

This walkthrough rebuilds the path from raw materials to a working system for: How Family Offices Can Use Claude + FMP MCP to Detect Portfolio Drift Before Rebalancing. The focus is operable steps, explicit checks, and code that you can drop into a repo without guessing intent. For the Overview stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Why Portfolio Drift Matters Before Rebalancing

When working through the Why Portfolio Drift Matters stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.

How Far Has Each Holding Moved From Target?

When working through the How Far Has Each stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.

How Large Is the Drift Relative to the Original Allocation?

When working through the How Large Is the stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours. When working through the How Large Is the stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Has the Portfolio Drifted at the Sector Level?

The Has the Portfolio Drifted stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

Which Holdings Are Driving the Change?

The Which Holdings Are Driving stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

FMP Data and Claude MCP Setup

The FMP Data and Claude stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve. The FMP Data and Claude stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Data Retrieved Through FMP MCP

For the Data Retrieved Through FMP stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Cite the passages that actually grounded the answer. Without citations, operators cannot tell hallucination from an indexing gap.

Why Dividend-Adjusted Prices Are Used

For the Why Dividend-Adjusted Prices Are stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

From Target Weights to Drift

For the From Target Weights to stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary. For the From Target Weights to stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Measuring Portfolio Drift and Review Thresholds

When working through the Measuring Portfolio Drift and stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.

Position-Level Review Rules

When working through the Position-Level Review Rules stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.

Sector-Level Drift

When working through the Sector-Level Drift stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours. When working through the Sector-Level Drift stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Measuring Overall Portfolio Drift

The Measuring Overall Portfolio Drift stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

Identifying the Main Contributors to Drift

The Identifying the Main Contributors stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

Running the Analysis with Claude

The Running the Analysis with stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve. The Running the Analysis with stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Act as an investment-research analyst supporting a family office.

Using only the Financial Modeling Prep (FMP) MCP server, analyze how far the following hypothetical portfolio has drifted from its original target allocation.

Do not use web search or outside data.

Portfolio:

MSFT — Target Weight: 20% — Initial Allocation: $200,000
NVDA — Target Weight: 15% — Initial Allocation: $150,000
JPM — Target Weight: 20% — Initial Allocation: $200,000
GOOGL — Target Weight: 15% — Initial Allocation: $150,000
XOM — Target Weight: 15% — Initial Allocation: $150,000
JNJ — Target Weight: 15% — Initial Allocation: $150,000

Total portfolio value at inception = $1,000,000.

Assume:
- no trades occurred after the initial allocation;
- no capital was added or withdrawn;
- no manual rebalancing occurred;
- transaction costs, taxes, and cash balances are outside the scope of this demonstration.

Analysis date: August 27, 2026.
Use August 26, 2026, the last completed U.S. trading session, as the ending price date.

Retrieve for each ticker:
- company name;
- sector;
- industry;
- dividend-adjusted historical price for January 2, 2026;
- dividend-adjusted historical price for August 26, 2026.

Use the FMP dividend-adjusted historical price series if available.

If an exact date is unavailable, use the closest valid trading date and state the date actually used.

Do not estimate missing FMP values.

Reconstruct the portfolio using the dividend-adjusted price change as a total-return proxy.

Calculate for each holding:
- growth factor;
- ending value;
- current portfolio weight;
- absolute drift in percentage points;
- relative drift as a percentage of target weight.

Classify each holding using these illustrative rules:

Within Range:
- absolute drift below 2 percentage points; AND
- absolute relative drift below 15%.

Monitor:
- absolute drift between 2 and 4 percentage points inclusive; OR
- absolute relative drift between 15% and 25% inclusive;
- provided Review Required has not already been triggered.

Review Required:
- absolute drift above 4 percentage points; OR
- absolute relative drift above 25%.

Also calculate target and current sector weights using FMP sector classifications.

Classify sector drift as:
- Within Range: below 3 percentage points;
- Monitor: 3–5 percentage points inclusive;
- Review Required: above 5 percentage points.

Calculate Portfolio Allocation Distance as:

0.5 × sum of the absolute position-level weight deviations.

Do not assign a Low, Medium, or High label to this metric.

Also calculate each holding's contribution to total absolute drift.

Based strictly on the calculated evidence, identify:
- the largest overweight;
- the largest underweight;
- Monitor positions;
- Review Required positions;
- the sectors with the largest drift;
- the holdings contributing most to total drift;
- the highest-priority deviations for analyst review.

Do not recommend buying, selling, trimming, adding to, or rebalancing any security.

If important price, sector, or classification data is missing or conflicting, use Review Required rather than guessing.

Do not claim that corporate events were checked unless data capable of verifying them was actually retrieved.

Present the results clearly and concisely using tables where useful.

Include:
- methodology and actual dates used;
- reconstructed portfolio weights;
- position-level drift;
- sector-level drift;
- Portfolio Allocation Distance;
- contribution to total drift;
- key findings;
- Review Required items;
- FMP MCP tools and data types used.

What Claude Found: Which Allocations Drifted the Most

For the What Claude Found Which stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

JNJ and XOM Moved Furthest Above Target

For the JNJ and XOM Moved stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

MSFT Became the Largest Underweight

For the MSFT Became the Largest stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary. For the MSFT Became the Largest stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Overall Allocation Distance Reached 4.15 Percentage Points

When working through the Overall Allocation Distance Reached stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.

JNJ and XOM Drove Half of Total Drift

When working through the JNJ and XOM Drove stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.

Sector Drift Stayed Within Range

When working through the Sector Drift Stayed Within stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours. When working through the Sector Drift Stayed Within stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

When Analyst Intervention Is Required

The When Analyst Intervention Is stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

A Threshold Breach Does Not Automatically Mean a Trade

The A Threshold Breach Does stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

Corporate Events May Explain Large Price Moves

The Corporate Events May Explain stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve. The Corporate Events May Explain stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Single-Holding Sectors Need Careful Interpretation

For the Single-Holding Sectors Need Careful stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

Actual Portfolio Activity Can Break the Simulation

For the Actual Portfolio Activity Can stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

Missing or Conflicting Data Should Trigger Review

For the Missing or Conflicting Data stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary. For the Missing or Conflicting Data stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

From Drift Detection to Ongoing Rebalancing Review

When working through the From Drift Detection to stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.

Operational checklist

The Operational checklist stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope.

Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.

Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

Add a smoke test that exercises the critical path in CI with fixtures, not live paid APIs, whenever budgets allow.

Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

Before promoting the stack, freeze versions, capture a golden transcript for the critical path, and confirm rollback steps. Shared environments need rate limits, tenancy checks, and a clear owner for secret rotation. Prefer boring reliability over clever one-off demos.

Batch note for f24d8fb9fdeb: keep provider keys out of the repo, set a per-session token ceiling, and store transcripts next to the eval fixtures so later model swaps stay comparable.