Documentation / Grade AI

Reads over MCPBeta

Let your own model, or Claude, read your organization's data through the assistant's reads.

reads over mcp · bash
curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Which campaigns started this month?" }],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://<MCP host>/mcp",
        "name": "grade",
        "authorization_token": "<agent token>"
      }
    ],
    "tools": [{ "type": "mcp_toolset", "mcp_server_name": "grade" }]
  }'
All documentation

The assistant's reads are also an MCP server. A model you run can call them as tools, and a person can connect Claude to them with their own Grade sign-in. Nothing on this server changes data.

Its URL is https://mcp.usegrade.com/mcp. People in your organization also find it in Grade, under Account settings → AI agents, and on the Developer page, beside the API base URL. During the beta, every other organization is refused with 403, and where the server is off it answers 404.

Your own model

Mint an agent token on your backend, as for a question (Quickstart), and send it as the bearer:

Header Value
Authorization Bearer <agent token>
Content-Type application/json
Accept application/json, text/event-stream

With Claude's MCP connector, pass the server and the token with each request:

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Which campaigns started this month?" }],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://<MCP host>/mcp",
        "name": "grade",
        "authorization_token": "<agent token>"
      }
    ],
    "tools": [{ "type": "mcp_toolset", "mcp_server_name": "grade" }]
  }'

Your model calls the reads it needs, on your key and at your cost. Grade keeps only which read was called and how it ended; your model's conversation never reaches Grade. The token lasts 15 minutes: mint another when it runs out, and keep it on your backend.

Claude, for a person

A person connects Claude with their own Grade sign-in, and no SDK key is involved. Claude then reads as that person, within what their role reaches, for up to 30 days, and they can disconnect it in Account settings → AI agents. The steps, with screenshots, are in the Help Center. ChatGPT comes later.

What it lists

The assistant's own reads, within the token's scopes: see Reads. Each answers at most 20 rows, with the full count. Actions are never listed: a change goes through the assistant, as a proposal a person confirms.

The protocol

Streamable HTTP without sessions, answered in JSON: one JSON-RPC message per POST, in the protocol revisions 2025-11-25, 2025-06-18 and 2025-03-26. A read that fails comes back as a tool result with isError: true and a sentence your model can act on.

Refusals

Status Code Meaning
401 No token, or one that does not verify or ran out. Mint another. A person's token from Grade is refused too: this server takes an application's.
401 session_expired The token ran out while Grade was answering. Mint another.
403 refused_access The server is not open to your organization (it opens to organizations that pay out through Grade), the key's scopes reach no read, or the person left your organization.
403 origin_refused A browser page on another origin sent the request.
404 The server is off on this environment.
429 rate_limited Over your application's share this minute. Wait as long as Retry-After says.
503 paused, AGENT_UNCONFIGURED The assistant is paused, off for your organization, or not configured on Grade's side.

Describe your program.

Grade turns it into a program it can track and pay.