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.
- 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.
- In ChatGPT or Claude, add TheWILL.ai as a connector and sign in with your TheWILL.ai account. The app never sees your password.
- Tick what the app may read. Firm records start unticked, so they are shared only if you tick them.
- 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.
- A firm owner or administrator switches AI apps on for the firm.
- On Connected apps in settings, they create a Gemini Enterprise connector for the firm.
- Copy the client ID and secret straight away. The secret is shown once.
- In the Gemini Enterprise admin console, add a custom MCP connector and enter the values below.
- 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
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
Step 1: Create a key for the agent
A separate, read-only key you can revoke on its own.
- Open the API keys page at
/account/developer/keysand choose Live on the Test / Live switch - Create a new key and name it after the agent, so you can tell it apart from your own integrations
- 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 - Set an expiry date, then copy the key straight away. It is shown once
Screenshot, for illustration only




Tip
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
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-RemainingandX-RateLimit-Resetheaders - 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_scopeslists 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
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
