Browse the documentation

Using Clarirad with Claude and OpenAI (MCP)

Run the Clarirad MCP server on your own machine so Claude, Cursor or an OpenAI agent can work with your tenant through an API key.

DevelopersAdministratorsLast updated

@clarirad/mcp is a Model Context Protocol (MCP) server that you run on your own machine. It gives an AI app, such as Claude Desktop, Claude Code, Cursor or an agent built with the OpenAI Agents SDK, a set of tools that call the Clarirad tenant API with one of your API keys.

How the data moves

Clarirad does not send anything to an AI provider itself. When the AI app uses a tool:

  • The AI app asks the MCP server, on your machine, to run the tool.
  • The MCP server calls the tenant API with your key and gets back what that key may see.
  • The AI app passes the tool result to its model provider, such as Anthropic for Claude or OpenAI for ChatGPT and OpenAI agents, as part of the conversation.

So what the model sees is what the key returns. Choose the key's scopes, sites and de-identification with that in mind: see Patient privacy with AI models.

Before you start

  • An API key issued under Settings, then API Keys, with the scopes for the tools you want to use. See Issuing a key and Scopes and gated fields.
  • The key's Used with setting matches the AI app: Claude (Anthropic) or OpenAI. It is chosen when the key is created and cannot be changed later.
  • The key's IP allowlist includes the public address of the machine that runs the MCP server. The calls come from that machine, not from the AI provider. See IP allowlist and API IP policy.
  • Node.js on that machine, so that npx can run the server.

Settings

The server reads two environment variables:

  • CLARIRAD_API_KEY (required): the key's secret, cr_live_....
  • CLARIRAD_REGION: au (the default) or cl. A key works only in the region that issued it.

There is no tenant setting. The key decides the tenant, as described below.

Claude Desktop

Open Settings, then Developer, then Edit Config, and add Clarirad to claude_desktop_config.json. Restart Claude Desktop afterwards.

{
  "mcpServers": {
    "clarirad": {
      "command": "npx",
      "args": ["-y", "@clarirad/mcp"],
      "env": {
        "CLARIRAD_API_KEY": "cr_live_...",
        "CLARIRAD_REGION": "au"
      }
    }
  }
}

Claude Code

claude mcp add clarirad --env CLARIRAD_API_KEY=cr_live_... -- npx -y @clarirad/mcp

Add --env CLARIRAD_REGION=cl before the -- for a Chilean key.

Cursor

Add the same mcpServers entry as for Claude Desktop to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json to use it in every project.

OpenAI Agents SDK (Python)

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main():
    async with MCPServerStdio(
        params={
            "command": "npx",
            "args": ["-y", "@clarirad/mcp"],
            "env": {"CLARIRAD_API_KEY": "cr_live_...", "CLARIRAD_REGION": "au"},
        }
    ) as clarirad:
        agent = Agent(name="Bookings", mcp_servers=[clarirad])
        result = await Runner.run(agent, "List tomorrow's appointments.")
        print(result.final_output)

Keep the secret out of source control: read it from your secrets manager or the environment rather than writing it into the file.

One tenant per key

The MCP server cannot choose a tenant. Clarirad's servers work out the tenant from the key, so the server can reach only the tenant that issued the key, and within it only what the key's scopes and site restriction allow.

Every call is audited against the key, as for any other use of the tenant API. Revoking the key cuts the MCP server off at once.

Tools

  • Patients: search and get patients; create and update patients.
  • Requests: list, get, create and update requests; attach a RadForms form to a request.
  • Appointments: list, get, book, update and cancel appointments.
  • Results: list and get signed results.

Each tool needs the matching scope on the key, such as appointments:cancel to cancel. A tool the key has no scope for is refused by the API.

Writes support a dry run, so the AI app can check that a booking or an update is valid and permitted before making it. Nothing can be deleted, no report can be signed off and nothing can be administered: those operations do not exist on the tenant API.

Patient details

A key used with OpenAI, and any key marked de-identified, replaces patient names and identifiers before anything leaves Clarirad. Read Patient privacy with AI models before you connect a key to patient data.