Developers · AI connector
Connect an AI app to Alethia.
Alethia runs an MCP server, so a person can connect their own AI app, such as Claude, ChatGPT or Cursor, to their workspace and ask it questions. The app signs in as that person and sees exactly what they may see. It is available on every plan, once a workspace admin allows it.
Server
The server URL
Add this URL to the AI app as a custom connector or MCP server. The app handles the sign-in.
https://app.alethiahq.com/api/mcp- Transport. Streamable HTTP. Requests are POST with JSON responses; the server keeps no session between calls and does not stream.
- Protocol versions. The newest the server supports is negotiated; 2025-11-25, 2025-06-18 and 2025-03-26 are accepted.
- Results. Compact JSON with ids and plain fields. Lists return up to 25 items by default and 100 at most, with a cursor for the next page. Names and other text are returned exactly as they were entered.
Sign-in
OAuth 2.1, with Alethia as the authorisation server
Each person signs in to Alethia and approves the connection. There are no shared keys or client secrets.
https://app.alethiahq.com/.well-known/oauth-protected-resource
https://app.alethiahq.com/.well-known/oauth-authorization-server- An unauthenticated call to the server answers 401 with a WWW-Authenticate header that points to the protected-resource metadata, which names Alethia as the authorisation server.
- The client registers itself through dynamic client registration, as a public client with no secret. Redirect URIs must use https, or http on localhost for desktop apps.
- The client starts an authorization code flow with PKCE (S256 only). The resource parameter must be the server URL above.
- The person signs in to Alethia, completes two-factor sign-in, picks one workspace they belong to, sees the app's name and what it is asking for, and approves or declines.
- Access tokens last one hour. Refresh tokens change on every use, and reusing an old one ends the connection. A connection lasts 30 days, then the person approves it again. Clients can revoke tokens at any time.
Permissions
Scopes
Read is always granted. Changes are the exception, not the default.
alethia:read- Always granted. Every read tool, limited to what the signed-in person may see in the workspace.
alethia:write- Offered on the sign-in screen only when Alethia has made changes available to that workspace, at the customer's request, and a workspace admin has switched them on. The person chooses whether to approve it. Adds the write tools.
Tools
What the AI app can read
Every tool answers under the same access rules as the person using Alethia directly: restricted records, viewer lists, personal details and confidential compliance work stay as closed to the app as they are to the person.
workspace_summary- An overview of the workspace as the signed-in person sees it.
search- Find entities, people and documents by name.
get_person_appointments- Every appointment one person holds across the workspace, in one call: directorships, manager, secretary and other roles.
list_entities- List entities, a page at a time.
get_entity- One entity's details.
get_entity_officers- An entity's directors, officers and other appointments.
get_entity_ownership- An entity's shareholders and ownership.
get_structure- The ownership chain above and below an entity, with effective (look-through) percentages at every level.
list_documents- List documents and their details. File contents are not returned.
get_document- One document's details, without the file itself.
list_tasks- List tasks.
list_compliance_deadlines- List compliance deadlines, such as filings coming due.
list_contracts- List contracts and agreements, including those expiring soon.
list_deals- List deals.
get_deal- One deal's details.
list_kyc_cases- List due diligence (KYC) cases the person is allowed to see.
get_kyc_case- One due diligence (KYC) case.
data_quality_check- Read-only checks for likely duplicates, missing details, roles that do not fit the legal form, and ownership that does not add up.
Changes
Task tools, when switched on
Listed only when Alethia has made changes available to the workspace at the customer's request, a workspace admin has switched them on, and the person approved changes when they connected. Every change is checked and recorded like one made in the app.
create_task- Create a task.
complete_task- Mark a task complete.
Controls
Who decides
A workspace admin allows AI connections in Settings, under AI connections. It is off until they switch it on, and switching it off disconnects every app in the workspace at once. Each person sees their own connected apps there and can disconnect any of them; admins see and can disconnect every connection in the workspace.
Privacy
Where the data goes
Alethia keeps workspace data in London. What a connected app reads is sent to the AI provider the person chose, under their own account with that provider, and that provider's terms apply to it.
Next
Continue reading
Overview
Developer portal
The REST API, webhooks and the OpenAPI document, for system-to-system integrations.
Read more →REST API
API keys
Workspace API keys are a different thing: they are for integrations, not for a person's AI app.
Read more →Contract
Errors & limits
The REST API's error envelope, status codes and rate limits.
Read more →See it with your own workspace.
We can walk through connecting an AI app to a workspace and what it can answer.