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

# MCP (Model Context Protocol)

> Read-only remote MCP for AI agents and ChatGPT connectors.

## Overview

Grain exposes a **read-only** remote MCP server for AI agents and connector platforms, including ChatGPT, Claude, Cursor, and other MCP clients. MCP uses the same Grain OAuth identity and organization permissions as the REST API.

| Item         | Value                              |
| ------------ | ---------------------------------- |
| MCP endpoint | `https://api.grainledger.com/mcp`  |
| Transport    | Streamable HTTP                    |
| Auth         | OAuth 2.1 (Sign in with Grain)     |
| Access mode  | Read-only tools only               |
| Org scoping  | Per tool call via `organizationId` |

## Authentication flow

1. MCP client discovers protected resource metadata from Grain.
2. Client completes OAuth 2.1 authorization code + PKCE with the Grain authorization server.
3. Grain issues a Supabase OAuth access token for the signed-in user.
4. Client calls MCP tools with `Authorization: Bearer <access_token>`.
5. For data tools, pass `organizationId` from `list_organizations`.

### Protected resource metadata

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET https://api.grainledger.com/.well-known/oauth-protected-resource
```

Returns OAuth Protected Resource Metadata (RFC 9728) with:

* `resource`: `https://api.grainledger.com/mcp`
* `authorization_servers`: Grain OAuth issuer

Unauthenticated MCP requests receive `401` with:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
WWW-Authenticate: Bearer resource_metadata="https://api.grainledger.com/.well-known/oauth-protected-resource"
```

See [Authentication](/authentication) for OAuth endpoints and consent.

## Organization scoping

MCP access tokens identify the signed-in user. Every data tool also requires `organizationId` so Grain knows which church's data to read:

1. Call `list_organizations` to get church IDs the user belongs to.
2. Pass `organizationId` on subsequent tool calls.
3. Permissions follow the user's role in that organization (same as the REST API).

Optional: call `get_my_permissions` to inspect allowed actions before querying data.

## Available tools (read-only)

| Tool                                      | Description                          |
| ----------------------------------------- | ------------------------------------ |
| `list_organizations`                      | Churches the user can access         |
| `get_my_permissions`                      | User permissions in one organization |
| `list_transactions` / `get_transaction`   | Bank transactions                    |
| `list_bills` / `get_bill`                 | Vendor bills                         |
| `list_donors` / `get_donor`               | Donors                               |
| `list_contributions` / `get_contribution` | Giving contributions                 |
| `list_pledges` / `get_pledge`             | Pledges                              |
| `list_households` / `get_household`       | Donor households                     |

All tools are annotated `readOnlyHint: true`. Write operations are not exposed through MCP.

MCP is read-only because the server exposes only read tools. OAuth clients receive standard Grain/Supabase access tokens; organization permissions still apply on every tool call.

## Connect in Cursor

Install Grain in Cursor with one click, or add the configuration manually.

<Card title="Add to Cursor" icon="square-terminal" href="https://cursor.com/install-mcp?name=grain&config=eyJ1cmwiOiJodHRwczovL2FwaS5ncmFpbmxlZGdlci5jb20vbWNwIn0%3D">
  Install Grain's remote MCP server in Cursor.
</Card>

Manual configuration:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mcpServers": {
    "grain": {
      "url": "https://api.grainledger.com/mcp"
    }
  }
}
```

Cursor will prompt you to complete Sign in with Grain when it connects to the production MCP endpoint.

## Connect in ChatGPT

In ChatGPT, add Grain as a connector when it is available to your workspace. Use the MCP URL `https://api.grainledger.com/mcp` and complete the Sign in with Grain flow when prompted.

## Revoking access

Users approve access on the Grain OAuth consent screen. To revoke:

1. Sign in to Grain at `https://app.grainledger.com`
2. Remove the connected application from your account (OAuth connected apps)
3. Or deny future authorization requests from that client

## Example prompts

After connecting an MCP client, these prompts are useful smoke tests:

1. "List my Grain organizations"
2. "What permissions do I have in organization `{orgId}`?"
3. "Show the 10 most recent transactions for organization `{orgId}`"
4. "List open bills for organization `{orgId}`"

Expected behavior: read-only JSON results. If the user's role lacks the required permission, Grain returns a permission error.

## Related

* [Authentication](/authentication) — OAuth 2.1 and Bearer tokens
* [Organizations](/organizations) — Organization IDs and membership