All documentation
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. |
