> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.usegrade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reads over MCP

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

**Beta.** The assistant API and its reads over MCP are in beta. They are open to every
organization that pays out through Grade, and parts are not available yet, as each page says.

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](https://api-docs.usegrade.com/agent/overview.md#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector),
pass the server and the token with each request:

```bash theme={null}
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](https://usegrade.com/v2/help#connect-ai-apps). ChatGPT comes later.

## What it lists

The assistant's own reads, within the token's scopes: see [Reads](https://api-docs.usegrade.com/agent/overview.md#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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.