Protocol reference

The protocol-level detail for connecting any MCP client to Lawtte. For what the server is and who can use it, start at the Lawtte MCP server; to get it working in Claude without any of this, use connect Claude.

Endpoint


Server URL	`https://www.lawtte.ai/api/mcp`
Transport	Streamable HTTP (`GET` and `POST` on the same URL)
Capabilities	`tools` only — no resources, no prompts, no sampling
Auth	OAuth 2.1 (preferred) or a Lawtte API key
CORS	Open, with `authorization`, `content-type`, `mcp-protocol-version` allowed; `OPTIONS` returns `204`

Access is limited to Lawtte Studio accounts. A principal that resolves to any other kind of firm authenticates fine and still gets 401 — the server exposes nothing to it.

Discovery

The server implements OAuth 2.0 Protected Resource Metadata (RFC 9728). An unauthenticated request returns 401 with the pointer in WWW-Authenticate:

curl -i -X POST https://www.lawtte.ai/api/mcp \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

HTTP/2 401
www-authenticate: Bearer resource_metadata="https://www.lawtte.ai/.well-known/oauth-protected-resource/api/mcp"

That document names the authorization server:

{
  "resource": "https://www.lawtte.ai/api/mcp",
  "authorization_servers": ["https://<project>.supabase.co/auth/v1"],
  "bearer_methods_supported": ["header"]
}

Follow the discovery chain rather than hard-coding the authorization server. It is an implementation detail and can move; the resource metadata URL will not.

OAuth 2.1

The authorization server publishes standard metadata at /.well-known/oauth-authorization-server and supports:

Feature	Value
Grant types	`authorization_code`, `refresh_token`
PKCE	`S256` (use it — `plain` is advertised but don’t)
Response types	`code`
Scopes	`openid`, `profile`, `email`, `phone`, `offline_access`
Dynamic client registration	Supported (RFC 7591)

Because registration is dynamic, a client needs no pre-issued credentials. The flow:

POST to the registration_endpoint from the authorization server metadata. You get a client_id back.

Authorize

Send the user to the authorization_endpoint with PKCE. Request offline_access if you want a refresh token.

The user picks a receptionist

Lawtte shows its own consent screen: the user signs in, chooses one Studio calling agent, and approves the call tools. That choice is stored as a grant against your client_id and their user — it’s what the server later resolves a token to.

Exchange and call

Swap the code at the token_endpoint and send the access token as Authorization: Bearer <token> on every MCP request.

One grant is one receptionist. A token never spans two Studio accounts, and a user who wants to switch re-approves. Grants are revocable at any time from Dashboard → Connect, and revocation takes effect immediately.

API-key authentication

For clients that can’t do OAuth — a local mcp-remote setup, a script, CI — the server also accepts a Lawtte API key as a bearer token:

Authorization: Bearer lawtte_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are created by the Studio account owner in Dashboard → Connect, shown once, and stored only as a SHA-256 hash. A key is bound to one firm and carries the same access as an OAuth grant for that firm.

A key can place real phone calls. Keep it in a file or secret store, never in a URL or a command argument — arguments are visible to every process on the machine. See Claude Desktop for the header-file pattern.

Tools

Three tools, described in plain language in connector tools. The schemas, for a client that needs them:

{
  "name": { "type": "string", "minLength": 1, "maxLength": 120 },
  "phone": { "type": "string", "minLength": 7, "maxLength": 32 },
  "objective": { "type": "string", "minLength": 1, "maxLength": 1000 },
  "context": { "type": "string", "maxLength": 4000 },
  "dry_run": { "type": "boolean" }
}

{
  "call_id": { "type": "string", "format": "uuid" }
}

{
  "since": { "type": "string", "format": "date-time" },
  "status": {
    "enum": ["blocked", "dialing", "in_progress", "completed", "failed"]
  }
}

place_call carries destructiveHint: true; the other two carry readOnlyHint: true. A client that surfaces those hints should require confirmation before place_call — it dials a real person. Results come back as a text content block holding JSON. Trailing whitespace and key order aren’t guaranteed; parse it, don’t pattern-match it.

Errors

Status	Meaning	What a client should do
`401`	No token, an invalid token, a revoked grant, or a firm that isn’t a Studio account	Re-run discovery and re-authorize. Don’t retry the same token.
`503`	The credential store is unreachable; the server fails closed rather than dialing	Retry with backoff. No call was placed.

Business-rule refusals are not HTTP errors. A call blocked by the Do Not Call list, the daily cap, the two-hour repeat rule, or calling hours returns a normal tool result with the reason in it — surface that text to the user rather than treating it as a failure. See limits and safety.

Connecting a client

MCP Inspector

Point it at https://www.lawtte.ai/api/mcp with an Authorization: Bearer <key> header, or let it run the OAuth flow. Good for confirming the tool list and running a dry_run before you write any code.

mcp-remote (stdio clients)

For clients that only speak stdio:

npx mcp-remote https://www.lawtte.ai/api/mcp \
  --header-file /absolute/path/to/header-file \
  --transport http-only

The header file holds one line: Authorization: Bearer lawtte_sk_…

Your own client

Any MCP SDK works. Connect over streamable HTTP to the server URL, attach the bearer token, and call tools/list to confirm you see place_call, get_call_result, and list_calls. If the list is empty, the principal resolved to something that isn’t a configured Studio account.

Before you go to production

Run place_call with dry_run: true first. It performs every check — number validation, Do Not Call, quota, calling hours — and dials nothing, so you can prove your integration end to end without calling anyone.

Then read limits and safety. The caps aren’t advisory: they’re enforced server-side before dialing and they fail closed.

Get started

Connect a client

Reference

Help

Protocol reference

Endpoint

Discovery

OAuth 2.1

API-key authentication

Tools

Errors

Connecting a client

Before you go to production

​Endpoint

​Discovery

​OAuth 2.1

​API-key authentication

​Tools

​Errors

​Connecting a client

​Before you go to production

Endpoint

Discovery

OAuth 2.1

API-key authentication

Tools

Errors

Connecting a client

Before you go to production