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.

Two kinds of keys: a read-only key can only look things up, and a read & write key can also make the changes above. You choose which when you create the key.

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 or Read & write 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. Access lasts 90 days (Claude will ask you to sign in again) and you can disconnect anytime in Settings → MCP Server.

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) or Read & write (also create tasks, update contacts, book meetings, edit articles).
• 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 create and complete tasks, update contact details, book meetings, and edit articles in your content schedule.

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."
• "Update the practice area on this contact to family law."

When you ask it to change something, your assistant shows you exactly what it's about to do first — nothing happens without the request being clear.

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 create tasks, update contacts, book meetings, and edit articles — but never send SMS or email on your behalf.
• 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.
• 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.
• Sensible limits. Keys have generous daily usage limits to protect your account; contact us if you need them raised.

Troubleshooting

"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 → API Access and use that one. A read-only key will politely refuse any change and tell you a write key is needed.

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.