Run Magister from any AI assistant.

# Magister MCP — agent connection playbook

MCP server URL (remote, streamable HTTP): https://mcp.magistermarketing.com/mcp
Public directory/review URL: https://mcp.magistermarketing.com/mcp/catalog

## 1. Account (skip if the user already has one)
- POST https://magistermarketing.com/api/signup
  body: { "email", "team_name", "project_name", "website_url" }
  (GET the same URL to discover the field schema.)
- The response contains a signup_url. Have the user open it in a browser and
  finish with Google sign-in using the same email. The account, organization,
  brand, and verified website context are created only after sign-in succeeds.
  The link expires in 30 minutes.
- If self-serve signup is temporarily paused, a not_invited response means no
  signup link was created; tell the user signup is unavailable and stop.

## 2. Connect
- Claude Code: claude mcp add --transport http --scope user magister https://mcp.magistermarketing.com/mcp
- Codex: codex mcp add magister --url https://mcp.magistermarketing.com/mcp
- Cursor: merge this entry into ~/.cursor/mcp.json (global) or
  .cursor/mcp.json (project), then authenticate. Its public client id has no
  secret and uses PKCE. The config requests the baseline read scope plus
  full_access (every current and future non-spend tool, approved once on the
  consent screen; not available to Free organizations); publish, send,
  ad-spend, and delegate scopes must still be added explicitly before
  requesting those actions:
{
  "mcpServers": {
    "magister": {
      "url": "https://mcp.magistermarketing.com/mcp",
      "auth": {
        "CLIENT_ID": "magister-cursor-public-v1",
        "scopes": [
          "read",
          "full_access"
        ]
      }
    }
  }
}
- If Cursor previously registered Magister with read only:
  After switching to this config or changing scopes, log out of the Magister server in Cursor's Tools & MCP settings, then reconnect. If Cursor still reuses an older OAuth session, run “Cursor: Clear All MCP Tokens” from the Command Palette and reconnect; that fallback also signs you out of other OAuth MCP servers.
- Grok chat: add the full MCP server URL above as a custom connector.
- Grok Build: merge this entry into .mcp.json, then authenticate:
{
  "mcpServers": {
    "magister": {
      "type": "http",
      "url": "https://mcp.magistermarketing.com/mcp/catalog"
    }
  }
}
- For another client, add a remote MCP server with the URL above in its
  connector or MCP settings. For Claude Desktop, merge this into
  claude_desktop_config.json and restart:
{
  "mcpServers": {
    "magister": {
      "url": "https://mcp.magistermarketing.com/mcp"
    }
  }
}

## 3. Authorize
- The client opens Magister's consent screen: the user picks an organization
  and scopes. Built-in Magister tools use the baseline grant; external account
  writes are opt-in, and money/live actions also require immediate confirmation.
- OAuth consent cannot widen the scopes requested by the client. In Cursor,
  add a new external-write scope to auth.scopes and reconnect before requesting it.

## 4. Verify
- Call the list-projects tool. Most tools take a project_id from that list.
- Keep the first check read-only: get the brand profile, current plan, existing
  audit health, or existing AI-visibility results.
- Built-in research, audits, AI visibility, plan compilation, and media
  generation use the baseline grant. Metered calls still pass the organization
  budget gate and record usage before any further call can exceed its cap.

## 5. Brands & organizations
- One connection covers the user's whole organization: list-projects returns
  every brand/client, and every tool takes a project_id — so switching brands
  is just referencing a different project in the same conversation.
- To work in a different ORGANIZATION, reauthorize the connector (client
  settings -> reconnect); the consent screen shows an organization picker when
  the user belongs to more than one. No reinstall — takes ~30 seconds.

MCP eligibility is confirmed for the selected organization at connection time.
Depending on the current Magister access policy, an active Connect or Agent
subscription may be required. If a tool needs an integration that isn't
connected, it returns a one-click connect link.
## Credits and the free trial
- Reads and plan-item tools are never metered, on any plan. Only audits (25 credits), plan rebuilds (25), AI-visibility runs (60), influencer discovery (25), and keyword research (3) draw down your organization's credits. The free trial includes 300 credits that never refill; when they run out, reads and plan updates keep working and metered tools return limit_reached with a link that opens the upgrade dialog. Ask your assistant for your credit balance at any time (get_credit_balance, never metered); it is asked to bring up upgrading only when you are down to roughly your last 60 credits, a tool is refused, or your trial is used up — from then on every reply says so until you upgrade.
- list_projects returns a billing block: plan, metered_tools, and for a Free
  organization credits_remaining plus upgrade_url. Mention upgrading only when
  that block carries a notice, a result carries _billing, or a tool returns
  limit_reached with reason free_trial_exhausted; otherwise say nothing about
  plans or credits.
- get_credit_balance (read scope, never metered) reports the plan, credits
  used and remaining, refill (never for Free, otherwise the period end),
  limit_reached, per-tool usage, and the upgrade_url. Call it whenever the
  user asks about credits, usage, or limits.
- Once a tool returns limit_reached with reason free_trial_exhausted, every
  metered tool is refused until an owner or admin upgrades, and every reply
  carries _billing until then. Say plainly that they need to upgrade, show
  upgrade_url, and do not retry or try another metered tool.