Connect an AI Agent

The Portfolio MCP server exposes a small set of read-only tools that wrap our Consumer API endpoints. AI agents that speak the Model Context Protocol can list your holdings, fetch transactions, summarise analytics, and read your watchlists, using the same authentication as the REST API and an allowance of their own at the same hourly rate your plan grants the REST API.

The endpoint is POST https://orchard72.com/api/v1/mcp/. Authenticate with your personal API key: Authorization: Bearer twai_…

1. Open the Developer Page and select Create key.
2. Give the key a recognisable name (e.g. “AI agent on laptop”).
3. Choose portfolio:read only. Every agent tool is read-only, so portfolio:write adds nothing an agent can use and only widens what a leaked key could do.
4. Tick estate:read or residency:read only if you want the agent to see your estate status or your residency day counts (see the tools below). Neither is included unless you tick it, and no other scope grants them.
5. Set an expiry date. Six to twelve months is a sensible starting point. You can rotate the key earlier at any time.
6. Copy the key (it starts with twai_) and store it in your agent’s configuration. The raw key is shown once. We never store it in plaintext.

• list_holdings: aggregated portfolio holdings with their most recent prices.
• list_transactions: buys, sells, dividends, and transfers, newest first. Filter with account_id, security_id (both account and security identifiers), date_from and date_to (inclusive, YYYY-MM-DD) and limit (1 to 500). Filtering is applied server side, and a value the server cannot read is rejected rather than ignored.
• get_analytics_summary: combined sector/currency allocation and performance for a chosen period (default 1y).
• list_watchlists: watchlists and their items.
• get_estate_status (needs estate:read): which estate documents you have (will, powers of attorney and similar), the status of each, and a suggested next step as a link into TheWILL.ai. Statuses only: never the content of a document, the people named in it or its file names.
• get_residency_day_counts (needs residency:read): days present per country between date_from and date_to (YYYY-MM-DD, at least 28 days and at most three years apart), with how close each country’s day-count threshold is, from Expat183. Counts only: never your location history, and never a conclusion about where you are resident.

Every agent tool is read-only, and that is a deliberate choice: recording a transaction needs a confirmation step an agent connection cannot show you. Changes to your portfolio are made in the app or through the Consumer API, and an agent moves your will or residency tracking forward only by handing you a link to open yourself.

• Agents connect using your own key. We never share your portfolio with a third-party AI provider without your explicit approval. That is a promise we apply across the platform.
• Use a read-only key with an expiry for agent work. Keep any portfolio:write key for your own integrations, never for an agent.
• MCP traffic has its own hourly allowance, at the same rate your plan grants the Consumer API but counted separately, so an agent cannot use up the allowance your own integrations rely on. It has the same one-hour sliding window and per-minute burst cap, and every response reports it in the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Rotate keys whenever you suspect compromise.
• You can revoke a key at any time from the Developer Page. Agents using a revoked key receive HTTP 401 immediately.

• -32001: the key is missing, invalid, revoked or expired. The agent should ask you for a valid key.
• -32002: the key lacks the scope the tool needs. Retrying will not help; create a key with that scope.
• -32003: your plan does not include the feature the tool needs.
• -32004: the agent allowance is spent. The agent should wait the number of seconds given, then retry.
• -32010: the tool itself failed. A later retry may succeed.