Professional API: AI agents

Let an AI assistant you already use read your practice’s appointments, enquiries and engagement letters.

Last reviewed

Use ChatGPT or Claude

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

  1. If you belong to a firm, a firm owner or admin must switch AI apps on for the firm first. It is off until they do.
  2. In ChatGPT or Claude, add TheWILL.ai as a connector and sign in with your TheWILL.ai account. The app never sees your password.
  3. Tick what the app may read. Firm records start unticked, so they are shared only if you tick them.
  4. Ask about your clients, matters and invoices 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. The API-key set-up below is for developers and other MCP clients.

Use Gemini Enterprise

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

  1. A firm owner or administrator switches AI apps on for the firm.
  2. On Connected apps in settings, they create a Gemini Enterprise connector for the firm.
  3. Copy the client ID and secret straight away. The secret is shown once.
  4. In the Gemini Enterprise admin console, add a custom MCP connector and enter the values below.
  5. Each member then signs in once from Gemini with their own TheWILL.ai account and ticks 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: pro: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 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 the MCP server does

One server, reached with the same key as the Professional API.

TheWILL.ai runs a Model Context Protocol (MCP) server. An MCP-compatible AI agent connects to it with your professional API key and can then answer questions about your practice, such as which appointments are booked this week or which engagement letters are still unsigned, by calling a small set of tools.

The agent runs on your side, with the AI provider you chose. We do not forward your practice or client data to any AI provider on your behalf. The server only answers the calls your agent makes with your key.

Note

Agent access uses the same plan entitlement as the Professional API. If your plan does not include API access, the Developer hub will not offer you a key. If you belong to a firm, a firm owner or admin must also switch on “Connect AI apps (ChatGPT, Claude)” in the firm’s AI settings. Test keys work on the REST API only, so use a live key for MCP tools.

Step 1: Create a key for the agent

A separate, read-only key you can revoke on its own.

  1. Open the API keys page at /account/developer/keys and choose Live on the Test / Live switch
  2. Create a new key and name it after the agent, so you can tell it apart from your own integrations
  3. Give it read access only. “Everything in your practice” (pro:read) reaches every agent tool. To keep an agent to part of your practice, choose individual areas instead, such as Clients or Matters: the agent then sees only the tools that read those areas. No agent tool needs a write scope
  4. Set an expiry date, then copy the key straight away. It is shown once

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 overview. Open API keys in the sub-navigation to create a separate key for your AI app, name it after the agent and copy it once.

Tip

Keep any key that holds pro:wills:write for your own integrations. An agent does not need it, and a separate agent key means revoking the agent never breaks anything else.

Step 2: Configure your agent

Point the agent at the server and hand it the key.

MCP-compatible AI agents

For Claude Code, save a block like the one below as .mcp.json in your project folder and keep it out of version control. Replace BASE_URL with the address you sign in at, and twai_… with the key from Step 1. Other clients take a similar entry; their documentation gives the exact file and field names. In the Claude apps and ChatGPT, add the URL as a custom connector instead: they sign in with your account rather than a key.

{
  "mcpServers": {
    "practice": {
      "type": "http",
      "url": "BASE_URL/api/v1/mcp/",
      "headers": {
        "Authorization": "Bearer twai_..."
      }
    }
  }
}

Any client that supports the MCP streamable HTTP transport can connect: requests are JSON-RPC 2.0 over POST to /api/v1/mcp/, with the key sent as a Bearer token in the Authorization header.

Discovery document

Agents that look servers up for themselves can read /.well-known/mcp.json on the same address. It names the endpoint, the MCP protocol version, the authentication scheme, the refusal codes below and where the published tool catalogue lives.

Available tools (v1)

Read-only tools, each mirroring a Professional API read collection.

  • get_practice_profile: your own professional profile and practice details, the same as GET /api/v1/pro/ext/me/
  • list_appointments: appointments booked with you, most recently scheduled first
  • list_client_approaches: enquiries directed at you, newest first
  • list_engagement_letters: your engagement letters and the status of each, newest first
  • list_matters: your matters, with no client details, and whether each client currently consents to you reading their file
  • get_matter_brief: the client’s file for one matter, only while that client’s consent is live. It counts against the same client-file allowance as GET /api/v1/pro/ext/matters/{id}/brief/
  • list_clients: your current clients, most recently changed first
  • list_client_wills: the wills on your client wills list and the status of each
  • list_invoices: every invoice you have raised, drafts included, newest first
  • list_conversations and list_conversation_messages: your message conversations, and the messages in one of them
  • get_practice_dashboard: the practice-overview figures your dashboard shows, over a 7, 30 or 90-day window

The list tools are paginated and accept updated_since, so an agent can fetch only what has changed since its last visit. Every tool returns what the matching Professional API collection returns, under the same scoping rules. An agent only ever sees your own practice’s records.

The agent is offered only the tools your key and plan allow: the tool list it receives is filtered by the key’s scopes and your plan, so it is never shown a tool it would be refused on.

Note

Every agent tool is read-only by design. Creating a will draft needs the pro:wills:write scope on the Professional API itself, where your own code decides what is sent.

Privacy and safety

  • What the tools return, including client names and appointment details, reaches whichever AI provider runs your agent. Check that this fits your own confidentiality and data-protection obligations before you connect one
  • Agent traffic has its own hourly allowance, counted separately from your Professional API allowance, so an agent cannot use up what your own integrations rely on. Every response reports it in the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers
  • Revoke the agent’s key from the Developer hub at any time. The next call made with it is refused

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, named in data.required_scope; when either of two scopes would do, data.accepted_scopes lists them both. Retrying cannot succeed; edit the key’s scopes or create a key with one of them
  • -32003: your plan does not include the feature the tool needs, named in data.feature
  • -32004: the agent allowance is spent. The agent should wait the number of seconds in data.retry_after, then retry
  • -32005: AI is switched off for your account, by you, your organisation or the platform, or limited to Private AI only. A connected agent is treated as AI, so it is refused until you change this in your AI settings. Retrying cannot succeed before then
  • -32010: the tool itself failed. A later retry may succeed

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.