Your Carrell library, in any assistant.

Connect

Add a remote MCP server with the URL https://app.carrell.ai/mcp and OAuth sign-in. A Carrell sign-in page opens, and the person allows access to their library.

• Claude. Settings › Connectors › Add custom connector, then enter the URL.
• ChatGPT. Plugins › Add custom MCP server, with the URL and OAuth.
• Other clients. The client needs MCP 2026-07-28 and OAuth with Client ID Metadata Documents. See Protocol.

Authentication

Clerk, at https://clerk.carrell.ai, is the authorization server. A request without a valid token gets HTTP 401 with a header that points to the server’s protected resource metadata (RFC 9728), which names Clerk.

WWW-Authenticate: Bearer resource_metadata="https://app.carrell.ai/.well-known/oauth-protected-resource/mcp", scope="profile email offline_access"

$ curl https://app.carrell.ai/.well-known/oauth-protected-resource/mcp
{
  "resource": "https://app.carrell.ai/mcp",
  "authorization_servers": ["https://clerk.carrell.ai"],
  "scopes_supported": ["profile", "email", "offline_access"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Carrell",
  "resource_documentation": "https://carrell.ai/guides/chatgpt-and-claude/"
}

• Clients identify themselves with a Client ID Metadata Document and use the authorization code flow with PKCE (S256). There is no registration endpoint.
• Ask for profile, email and offline_access. The last gives a refresh token, so the connection lasts.
• Send the access token as Authorization: Bearer …. The server accepts only an OAuth access token whose audience includes https://app.carrell.ai/mcp. Any other token gets 401 with error="invalid_token".
• Each token acts for one person, and the tools see only that person’s library.

Protocol

The server speaks MCP 2026-07-28 over HTTP and nothing older. It keeps no session: each POST carries its protocol version, client and capabilities, and stands on its own. Call server/discover to read the server’s name, its supported versions and its instructions. A client that starts with initialize, as clients of earlier versions do, is refused.

curl https://app.carrell.ai/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: search" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": { "query": "grace", "passage": "Romans 8" },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {},
        "io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0" }
      }
    }
  }'

The answer comes as JSON or as one server-sent event. Each tool returns its result as structuredContent, and the same JSON as text in content.

The server’s instructions tell the model that library material is the person’s own, not Scripture and not necessarily right, that unreviewed text may have reading mistakes, and that it should say which item it is drawing on.

search

Finds passages in the library, best first, grouped by item. Every tool is marked read-only, not destructive, idempotent and closed-world.

{
  "results": [{
    "id": "n2",
    "title": "Grace for the whole world.",
    "kind": "note",
    "date": "2026-01-05",
    "text": "Grace for the whole world.",
    "linkedToPassage": true,
    "unreviewed": false
  }]
}

A result can also have source (a sermon’s speaker and church), at (the moment in a sermon, as mm:ss) or page. unreviewed means Carrell read the text from a photo or a recording and the person hasn’t checked it yet.

fetch

Reads one item by its id: a note’s text, a photographed item’s text, or a window of a sermon’s transcript with each paragraph stamped [mm:ss]. Read from the start, a sermon also comes with its summary and outline.

{
  "id": "…",
  "title": "Romans 8: No Condemnation",
  "text": "[0:00] This morning we come to Romans 8…",
  "metadata": {
    "kind": "sermon",
    "source": "Pastor Lee, Grace Church",
    "from": "0:00",
    "to": "10:00",
    "truncated": true,
    "unreviewed": false
  }
}

When truncated is true, there is more: call fetch again with from set to to.

recent_items

Lists the newest items, newest first, by when they were recorded or captured. Use it when there is nothing to search for, as in “last Sunday’s sermon.”

It returns { "items": [...] }, each with id, title, kind, date, unreviewed and, when there is one, source.

Errors

A tool that can’t do what it was asked returns a result with isError: true and a message the model can act on, so it can correct itself and try again.

A missing or rejected token gets HTTP 401, as Authentication describes, before the request reaches a tool.

Privacy

• The server never writes, changes or deletes anything. It can’t see highlights, bookmarks or Ask conversations.
• What it reads goes to the client, e.g., OpenAI or Anthropic, as part of the conversation, and their terms apply there.
• Carrell doesn’t keep a copy of what was searched or read. The privacy policy has the details.