Skip to main content

​
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.
ItemValue
MCP endpointhttps://api.grainledger.com/mcp
TransportStreamable HTTP
AuthOAuth 2.1 (Sign in with Grain)
Access modeRead-only tools only
Org scopingPer 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

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: 
WWW-Authenticate: Bearer resource_metadata="https://api.grainledger.com/.well-known/oauth-protected-resource"
See 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)

ToolDescription
list_organizationsChurches the user can access
get_my_permissionsUser permissions in one organization
list_transactions / get_transactionBank transactions
list_bills / get_billVendor bills
list_donors / get_donorDonors
list_contributions / get_contributionGiving contributions
list_pledges / get_pledgePledges
list_households / get_householdDonor 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.

Add to Cursor

Install Grain’s remote MCP server in Cursor.
Manual configuration: 
{
  "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.
Last modified on July 9, 2026