Professional API: AI Agents

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

1. Open the Developer section of your professional dashboard
2. Create a new key and name it after the agent, so you can tell it apart from your own integrations
3. Give it the pro:read scope only. Every agent tool needs pro:read, and none needs anything more
4. Set an expiry date, then copy the key straight away. It is shown once

MCP-Compatible AI Agents

Add a server entry like the one below to your MCP client’s configuration. Replace BASE_URL with the address you sign in at, and twai_… with the key from Step 1. Your agent’s documentation gives the exact file and format.

{
  "mcpServers": {
    "practice": {
      "transport": "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.

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

• 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 section at any time. The next call made with it is refused

• -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. Retrying cannot succeed; create a key with pro:read
• -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
• -32010: the tool itself failed. A later retry may succeed