MCP & API

What you can do

Superpractice speaks MCP (the Model Context Protocol), the open standard AI assistants use to connect to outside tools. Once connected, your AI assistant can read and act on your firm's data the same way your dashboards do — scoped to your organization, with the exact permissions you choose.

Three kinds of keys: a read-only key can only look things up, a read & write key can also make the changes above, and a read, write & send key can additionally text and email your contacts on your behalf. You choose which when you create the key. Sending texts requires a default SMS number assigned to you and a verified A2P registration for your firm; your AI tool will tell you if either is missing.

Connect your AI tool

Every tool connects to the same server address. Claude and ChatGPT sign in with your Superpractice account — no key to copy. CLI tools (Claude Code, Codex) authenticate with an API key instead. Pick your tool below.

https://app.superpractice.com/api/mcp

Claude (web & desktop)

Claude connects with your Superpractice sign-in — no API key needed. Open Settings → Connectors → Add custom connector, then:

• Name: Superpractice
• URL: https://app.superpractice.com/api/mcp
• Click Add, then Connect — a Superpractice sign-in window opens. Choose Read only, Read & write, or, for owners and admins, Read, write & send, and approve.

That's it — start a chat and Claude can use Superpractice automatically. Owners and admins can grant read & write; team members connect read-only unless the firm turns on Team members can make changes using the Superpractice MCP (see Team access). Access lasts 90 days (Claude will ask you to sign in again) and you can disconnect anytime in Settings → MCP Server.

Using Clio? Add the separate Superpractice Clio connector too, so Claude can read and work in your firm's Clio. See the Clio assistant guide.

ChatGPT

In ChatGPT, turn on Developer mode (Settings → Connectors → Advanced), then Add a connector:

• URL: https://app.superpractice.com/api/mcp
• Authentication: choose OAuth to sign in with your Superpractice account (recommended), or paste an API key — sp_live_your_key

After it connects, ChatGPT can call Superpractice tools inside a conversation.

Claude Code

Run this once in your terminal (replace the key):

claude mcp add --transport http superpractice https://app.superpractice.com/api/mcp \
  --header "Authorization: Bearer sp_live_your_key"

That's it — the superpractice tools are now available in every Claude Code session. Type /mcp to confirm it's connected.

Codex

Codex reads MCP servers from its config file (~/.codex/config.toml). Add this block:

[mcp_servers.superpractice]
url = "https://app.superpractice.com/api/mcp"
http_headers = { Authorization = "Bearer sp_live_your_key" }

Restart Codex and the Superpractice tools will be available. (In the CLI you can also run codex mcp add if your version supports it.)

Cursor

Add this to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally), replacing the key:

{
  "mcpServers": {
    "superpractice": {
      "url": "https://app.superpractice.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sp_live_your_key"
      }
    }
  }
}

Reload Cursor and the Superpractice tools appear under MCP in settings.

Other MCP clients

Any tool that supports remote MCP servers (Streamable HTTP) can connect with this generic shape — the field names vary slightly by tool, but the URL and the Authorization header are always the same:

{
  "mcpServers": {
    "superpractice": {
      "url": "https://app.superpractice.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sp_live_your_key"
      }
    }
  }
}

If your tool supports OAuth for remote MCP servers, you can usually skip the key entirely — point it at the URL and it will walk you through the Superpractice sign-in, same as Claude.

API keys (CLI tools & scripts)

Most people never need a key. Claude and ChatGPT sign in with your Superpractice account. Keys exist for tools that don't support sign-in (Claude Code, Codex, Cursor, custom scripts).

Only organization owners and admins can create keys. In Superpractice, go to Settings → MCP Server and click Create key.

• Give it a name you'll recognize, like "Claude" or "My laptop".
• Choose Read-only (look things up), Read + write (also make changes), or Read + write + send (also text and email your contacts, with a check before each send).
• Copy the key when it appears. It starts with sp_live_ and is shown only once — store it somewhere safe. If you lose it, rotate or create a new one.

Everything the key can see or do is scoped to your organization only.

What data is available

Your assistant can reach everything your dashboards show, scoped to your organization. You never write queries yourself — just ask in plain English and the assistant picks the right data.

A read & write key adds the ability to make changes, including:

• create, update, and complete tasks
• create and update contacts, notes, and matters
• book, move, and cancel meetings
• record payments
• edit articles in your content schedule, and track keywords and competitors
• save memories for your assistant
• save a new skill as a draft (an owner or admin reviews and publishes it in Superpractice)
• for owners and admins, manage services, knowledge, team invites, and voice agents
• permanently delete records

The tools are grouped by area, with looking things up kept separate from making changes. Sending texts and emails is its own tool and needs a read, write & send key.

Example questions

Ask naturally. Here are things people ask on day one:

Marketing & ROI

• "What was our total ad spend last month, broken down by channel?"
• "What's our cost to acquire a client from Google last month, with ROAS and LTV-adjusted ROAS?"
• "Show me Google search terms that spent money but produced no booked meetings."
• "Compare Meta cost per lead by practice area over the last 6 months."
• "Chart our weekly ad spend over the last 90 days versus the previous period."

Sales & pipeline

• "How much revenue did we close this month versus last?"
• "What's our open pipeline by stage?"
• "Which rep has the highest close rate this quarter?"
• "Who should I follow up with this morning?"

Clients & getting things done

• "How many new leads did we get from Google this week?"
• "Show me the full timeline for the Martinez contact — calls, ads, forms, meetings."
• "Create a follow-up task for the Johnson contact for tomorrow."
• "Book a 30-minute intro call for jane@example.com on Thursday at 2pm."
• "Send Jane our booking link for a strategy call." It reads your meeting types with their descriptions, picks the one that fits, and shares that meeting type's booking page.
• "Update the practice area on this contact to family law."

When you ask it to change something, AI tools such as Claude ask before running the change, unless you set that tool to Always allow. Permanent deletes are the one tool marked as destructive, so they are always asked about.

Two changes never run from your AI tool alone: buying a phone number and putting a voice agent live. They post an approval card to the Superpractice assistant chat of the person who asked. Nothing happens until an owner or admin approves it there, and the request expires after 24 hours.

Team access

Owners and admins choose what team members (people who aren't owners or admins) can do, in Settings → MCP Server → Team access:

• Team members can make changes using the Superpractice MCP: off by default. Off, team members connect read-only. On, they can connect with Read & write on the Superpractice connector. A team member who connected while it was off reconnects once and picks Read & write. The Clio connector has its own switch, Team members can make changes in Clio, on the Clio assistant card.
• Turning it off takes effect on the next request; their connection keeps working read-only.
• Sending texts and emails always stays with owners and admins.

Every call on both connectors is recorded in your firm's activity log with who asked, which tool and whether it worked.

Security & permissions

• Your data only. A key can only ever see and change data in the organization it was created for — never another firm's.
• You control what it can do. Read-only keys can't change anything. Read & write keys can make changes, but never send SMS or email on your behalf. Read, write & send keys can, with a check before each send.
• Keys are stored securely. We keep only a one-way hash — the key itself is shown once and never stored, so even we can't read it back.
• Your AI tool's own terms apply. What your AI tool reads through Superpractice is sent to that tool's provider under your account and plan with them. Superpractice's zero data retention covers our own AI features, not your AI tool, so check its data and training settings.
• Rotate or revoke anytime. In Settings → MCP Server, rotate a key to swap its secret, or revoke it to cut off access immediately. You can see each key's recent usage there too.
• Skills never grant access. A skill guides how your tool works; it can't widen what a key may see or do, or approve a send. With a personal key, your tool sees only the skills you can see. A firm-wide key sees only the skills shared with Everyone on the team; a skill shared with selected people never reaches it. Skills Superpractice provides are never readable here.
• Sensible limits. Keys have generous daily usage limits to protect your account; contact us if you need them raised.

Troubleshooting

Nothing happens when I click Connect in Claude

Your browser blocked the sign-in window. In Chrome, open claude.ai's site settings (the icon at the left of the address bar), set Pop-ups and redirects to Allow, reload and click Connect again. In Safari: Safari > Settings for claude.ai > Pop-up Windows > Allow. Or connect from the Claude desktop app, which opens your browser instead.

"Unauthorized" or the connection fails

Double-check the key is pasted with Bearer in front of it, and that the key hasn't been revoked or expired. Rotating the key in Settings gives you a fresh secret.

My tool asks for "read-only" but I need to make changes

Create a Read + write key in Settings → MCP Server and use that one. A read-only key will politely refuse any change and tell you a write key is needed.

"This is turned off for this firm"

Your AI tool sees the same pages and switches you do in Superpractice. If a part of Superpractice is turned off for your firm, the tool says which one, for example "Google Ads › Negatives is turned off for this firm". Ask Superpractice support to turn it on. Actions for owners and admins say so when someone else asks.

Claude doesn't show a header field

Custom request headers on Claude's web/desktop connectors are rolling out gradually. In the meantime, Claude Code, ChatGPT, and Codex all support the key today.

The numbers should match my dashboards

They do — the assistant reads the same data your dashboards use. Ad-platform figures are live and may differ by a few cents from a moment ago as the ad networks finalize them.