MCP for AI agents

The API ships a Model Context Protocol server at /mcp, so AI agents can read clinic data through well-described tools instead of raw HTTP. It's built on the official MCP SDK, is stateless (JSON responses, no SSE), and is backed by the same endpoints and scopes as REST - so an agent can never do anything a REST client with the same key couldn't.

#Endpoint

POST https://api.smile-app.co.il/mcp
Authorization: Bearer sk_live_...

GET and DELETE on /mcp return 405 - there's no standalone SSE stream. Authentication is the same sk_live_... bearer key; the agent's identity and scopes are derived per request.

#Tools

Each tool maps to a REST endpoint and requires the matching *:read scope. Tool descriptions guide the agent on when to call each one.

Tool	Does	Scope
`smile_whoami`	Returns the clinic and the scopes this key holds. Call first to learn what's possible.	(none)
`smile_get_catalog`	Lists reference data: branches, types, statuses, treatments, providers.	`catalog:read`
`smile_search_patients`	Searches patients by phone, email, or name.	`patients:read`
`smile_get_patient`	Fetches one patient (with `detailed` for full identity).	`patients:read`
`smile_list_appointments`	Lists appointments by date and branch/provider/patient/status.	`appointments:read`
`smile_find_availability`	Finds free slots for a branch over a date range.	`availability:read`
`smile_list_treatments`	Lists treatments recorded for a patient.	`treatments:read`
`smile_list_payments`	Lists a patient's payments (amount, method type, refund flag).	`payments:read`
`smile_describe_metrics`	Lists what can be aggregated: datasets, measures, dimensions, filters. Call before `smile_aggregate`.	`analytics:read`
`smile_aggregate`	Runs one server-side aggregation (GROUP BY) and returns grouped rows + grand totals.	`analytics:read`

Same contract, agent-friendly shapes

Tools return the same compact, embedded-reference objects as REST and default to the concise format - keeping token usage low. Agents resolve names from ids without extra calls.

Aggregate, don't enumerate

For any "total / count / average per X" question, reach for smile_describe_metrics then smile_aggregate — one call returns the figure straight from the database. Listing every patient and summing rows in the model is slow, expensive, and error-prone. See Analytics.

#Connect from Claude Code

Run the gateway, mint a key with read scopes, then register the remote MCP server with that key:

claude mcp add --transport http smile-public-api \
  https://api.smile-app.co.il/mcp \
  --header "Authorization: Bearer sk_live_..."

Then in a Claude Code session, run /mcp to confirm the tools are connected and ask in natural language:

List the clinic's branches.
Find the next free slot at branch 1 this week.
What treatments were recorded for patient 8842?
What was the net revenue per provider in the first half of 2026?

Manage the connection with claude mcp list, claude mcp get smile-public-api, and claude mcp remove smile-public-api.

#Connect from Claude Desktop (custom connector)

Claude Desktop adds remote MCP servers by URL and authenticates them over OAuth 2.1 — there's no place to paste a raw header. The gateway is its own OAuth Authorization Server for exactly this flow, so no extra service is needed.

In Claude Desktop, go to Settings → Connectors → Add custom connector and enter:

https://api.smile-app.co.il/mcp

Claude then runs the standard connector handshake automatically:

Discovery — a 401 from /mcp advertises the authorization server via WWW-Authenticate and the protected-resource metadata (RFC 9728).
Registration — Claude registers itself dynamically (RFC 7591); nothing to configure by hand.
Consent — a browser window opens asking you to paste a SmileCloud API key (sk_live_…). The key is the login: the connector inherits that key's clinic and scopes, and can never exceed them.
Done — Claude exchanges the grant (with PKCE) for a connector token and the tools above appear in the desktop app.

Revoking a connector

A connector grant is a derived, scoped child of the key you pasted. Revoking that key — or the grant itself — immediately invalidates the connector. Mint a dedicated key with just the scopes the connector should have.

#Connect from the Messages API

The server also works as an MCP connector for the Anthropic Messages API (mcp-client beta), passing the key as the connector's authorization token. Point the connector at https://api.smile-app.co.il/mcp.

Scopes still apply

An agent can only use a tool whose scope its key carries. Calling smile_list_payments with a key that lacks payments:read returns an authorization error - so mint agent keys with exactly the scopes the agent should have.