Security and scopes

An AI agent with access to your analytics is a trust decision. This page states what Grain does with the credentials that an MCP client holds, and how you stay in control.

Credential paths

The MCP endpoint accepts three kinds of credentials, in this priority order. Most users use only the first one.

Path	Header	Who uses it	Tools	Tenant source
OAuth	`Authorization: Bearer mcpat_…`	Claude.ai, Claude Desktop, Claude Code, Cursor, ChatGPT, and any MCP client with OAuth support.	The tools of the granted scopes.	Pinned at consent. Fixed for the life of the token.
Auth0 bearer	`Authorization: Bearer eyJ…` (a signed JWT)	Same-origin code in the Grain dashboard. Grain forwards the token as is to `grainsvc`.	The full tool surface.	The `X-Grain-Tenant` header or the `?tenant=` query parameter.
API key	`X-API-Key: <tenant secret>`	Server-to-server integrations that cannot do OAuth. This path predates MCP.	`grain.events.list`, `grain.query`, `grain.query.count`, `grain.dimensions.discover`. No scope filter. The key declares its permissions.	The key.

Grain issues the OAuth tokens from its own OAuth 2.1 server after you click Authorize in the browser. Read Authentication for the API key.

Scopes

Scopes are the control plane. A client names the scopes it needs when it asks to authorize. You can approve fewer scopes than the client asks for. The consent screen describes each scope in plain English.

Scope	Tools	Question it answers
`mcp:read`	`grain.events.list`, `grain.dimensions.discover`, `grain.integration.status`	”What is in this tenant?”
`mcp:query`	`grain.query`, `grain.query.count`, `grain.query.compare`, `grain.query.digest`	”What happened?”
`mcp:investigate`	`grain.correlate_event`, `grain.track.analyze`, `grain.segment.compare`, `grain.sessions.cluster`	”Why did it happen?”

If an agent only writes weekly digests, approve mcp:read and mcp:query and leave mcp:investigate off. You can connect again later and grant more. Read Tools for the inputs of each tool. There is no write scope. No MCP tool creates, updates, or deletes anything: not a segment, not a track, not a user. You can grant all three scopes to a trusted client without a risk of a change.

Token storage

Item	Storage	Lifetime
Grain tokens (`mcpat_…`, `mcprt_…`)	SHA-256 hash only. The plaintext leaves Grain one time, in the `/oauth/token` response. A database dump cannot produce a valid token.	The access token is short-lived. The refresh token rotates on refresh.
Upstream Auth0 tokens	AES-GCM ciphertext, encrypted in the application before the insert. The key is in `MCP_SESSION_ENC_KEY`, never in the database. No plaintext Auth0 token is stored or logged.	The Auth0 lifetime.
Authorization codes	Single use. An atomic compare-and-swap redeems the code. A leaked code cannot be spent a second time.	60 seconds
PKCE	`S256` only. Grain rejects the `plain` `code_challenge_method` and issues no client secrets. OAuth 2.1 and RFC 8252 require this.	Per authorization
OAuth tables (`mcp_oauth_clients`, `mcp_oauth_codes`, `mcp_oauth_sessions`)	Row-level security locks the tables to `service_role`. The anon key cannot read a row.	Not applicable

Connections

Every active MCP client is listed at Settings → Connectors → MCP clients. For each connection the page shows:

Column	Meaning
Client name	The name captured during Dynamic Client Registration, for example `Claude Desktop` or `Cursor`.
Workspace	The tenant that the session is pinned to. A workspace in the dashboard is a tenant.
Scopes	The scopes you granted.
Connected	When you authorized the client.
Last used	When the client last called a tool with success.
Session ID	A short opaque handle for support.

Revoke a connection

Open Settings → Connectors → MCP clients.
Click Revoke on the connection.
Confirm in the dialog. Grain sets the revoked_at timestamp of the session at once.

The next tool call of the client returns 401 with a WWW-Authenticate header. A compliant client then asks you to authorize again or marks the server as disconnected.

Revocation is instant on the Grain side, but some clients cache the tool list in memory. If a revoked client still shows tools, restart the client. Every tool call fails after revocation.

Workspace isolation

An MCP session is pinned to exactly one tenant, chosen at consent.

You cannot switch the tenant in a session. To let an agent read a different tenant, authorize a second connection.
Every tool call checks the tenant against the session again. A user who is removed from a tenant loses MCP access to it on the next tool call of the client.
The consent flow checks your membership of the chosen tenant again before it issues an authorization code. A stale membership cannot pass.

Logging

Log	Holds	Does not hold
Request	Method, tool name, tenant of the caller, elapsed milliseconds, budget consumed.	Arguments, result bodies.
Error	Normalized error message and HTTP status.	Stack traces, except in development.
Audit	Every successful tool call updates `last_used_at` on the session row. This is the “Last used” column.

A plaintext token never appears in a log. If you see one, it is a bug.

Checklist for teams

Connect a test tenant first. Send a low-volume or staging site to Grain, connect the AI client to that tenant, and read a few sessions. Move to production after that.
Grant the minimum scope that works. If the agent only writes briefings, mcp:read and mcp:query are enough. Add mcp:investigate when the agent needs it.
Read the MCP clients page every week, and after a team member leaves. Revoke every connection whose “Last used” is “never” or older than your tolerance.
Rotate the tenant API key every year. This applies only to the X-API-Key path. OAuth sessions rotate on refresh.

Coding agents

MCP server

Credential paths

Scopes

Token storage

Connections

Revoke a connection

Workspace isolation

Logging

Checklist for teams

​Credential paths

​Scopes

​Token storage

​Connections

​Revoke a connection

​Workspace isolation

​Logging

​Checklist for teams

Credential paths

Scopes

Token storage

Connections

Revoke a connection

Workspace isolation

Logging

Checklist for teams