Connect an AI agent

Use ChatGPT or Claude with one sign-in and no API key, or connect any Model Context Protocol (MCP) compatible agent with your own personal API key, the same key you use for the Consumer API.

Last reviewed

Screenshot, for illustration only

The Developer page under Account, where API keys and webhook endpoints are created and managedThe Developer page under Account, where API keys and webhook endpoints are created and managed
The Developer page under Account, where API keys and webhook endpoints are created and managedThe Developer page under Account, where API keys and webhook endpoints are created and managed
The Developer page under Account, where you create the personal API key an AI agent uses.

Use ChatGPT or Claude

One sign-in, no API key to copy or paste.

  1. In ChatGPT or Claude, add TheWILL.ai as a connector and sign in with your TheWILL.ai account. The app never sees your password.
  2. Tick what the app may read. Estate and firm records start unticked, so they are shared only if you tick them.
  3. Ask about your plans in your own words. The tools are read-only: they can read your data but cannot change it.

Disconnect at any time from Connected apps in your settings. Read more on connecting TheWILL.ai to your AI assistant.

Use Gemini Enterprise

For organisations on Google’s Gemini Enterprise or Gemini Business.

  1. In the Developer hub, create a Gemini Enterprise connector.
  2. Copy the client ID and secret straight away. The secret is shown once.
  3. In the Gemini Enterprise admin console, add a custom MCP connector and enter the values below.
  4. You then sign in once from Gemini with your TheWILL.ai account and tick what it may read, on the same consent screen ChatGPT and Claude use.
  • Client ID and client secret: from the connector you created
  • MCP server URL: https://thewill.ai/api/v1/mcp/
  • Authorisation URL: https://thewill.ai/api/v1/oauth/authorize/
  • Token URL: https://thewill.ai/api/v1/oauth/token/
  • Scopes: portfolio:read residency:read estate:read offline_access
  • Redirect URI (already set on our side): https://vertexaisearch.cloud.google.com/oauth-redirect

The offline_access scope lets Gemini stay signed in between chats. The tools Gemini can call are read-only, as for every AI app: they can read what each person ticks but cannot change it.

Keep the secret safe

Only you and your Gemini administrator should hold the client secret. On its own it reads nothing: each person must still sign in and consent. Rotate the secret from the connector at any time; the old one keeps working for 24 hours so Gemini can be updated. Revoking the connector disconnects everyone who signed in through it straight away.

What is the MCP server?

A standard agent interface, backed by the same data your REST API uses.

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://thewill.ai/api/v1/mcp/. Authenticate with your personal API key: Authorization: Bearer twai_…

Your data, your call

Agents connect with your own API key. We never forward your portfolio data to a third-party AI provider on your behalf. If an agent uses an external model, that is a connection you have set up under your own contract with that provider.

Step 1: Create a personal API key

  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.

The quicker way: Connect an AI assistant

The Settings tab of the same Developer Page has a Connect an AI assistant panel that does Steps 1 and 2 for you: it creates a key carrying the scopes the assistant tools use, fills that key into a ready-to-copy setup for Claude Code, Claude Desktop or any MCP client, and has a Test connection button that tells you whether the key gets through, or exactly why not. That key has no expiry date until you set one, and you can edit or revoke it under API keys like any other.

Step 2: Configure your agent

MCP-compatible AI agents

For Claude code, save the block below as .mcp.json in your project folder and keep it out of version control. Other clients that read an mcpServers file take a similar entry; their documentation gives the exact file and field names. Replace twai_… with the key you created in Step 1. In the Claude apps and ChatGPT, add https://thewill.ai/api/v1/mcp/ as a custom connector instead: they sign in with your account rather than a key.

{
  "mcpServers": {
    "thewill-portfolio": {
      "type": "http",
      "url": "https://thewill.ai/api/v1/mcp/",
      "headers": {
        "Authorization": "Bearer twai_..."
      }
    }
  }
}

Other MCP clients

Any client that supports the MCP streamable HTTP transport can connect. Point the client at https://thewill.ai/api/v1/mcp/ and send your key in the Authorization header as a bearer token.

Discovery document

Agents that look servers up for themselves can read https://thewill.ai/.well-known/mcp.json. It names the endpoint, the MCP protocol version, the authentication scheme, the error codes below and the address of the published tool catalogue.

Available tools (v1)

All v1 tools are read-only and share one agent rate limit, separate from your REST API allowance.

  • 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.
  • list_estate_* tools (need estate:read): one read-only list per estate record type, such as list_estate_wills, list_estate_gifts, list_estate_vault_documents and list_estate_todos, plus the three list_estate_residency_* lists from the residency tracker. Each returns only your own records, as statuses and metadata rather than document content.

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.

Privacy and safety

  • 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.

When a call is refused

Each refusal has its own JSON-RPC error code, so an agent can tell waiting from asking you.

  • -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.

Related topics

Can’t find what you’re looking for?

Our support team is here to help. Contact us and we’ll get back to you as soon as possible.

Contact us

We use cookies to improve your experience. See our Cookie policy (opens in a new tab) for details.