Security and scopes

An AI agent with access to your analytics is a trust decision. This page states what GrainQL 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 GrainQL dashboard. GrainQL 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.

GrainQL 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
GrainQL tokens (`mcpat_…`, `mcprt_…`)	SHA-256 hash only. The plaintext leaves GrainQL one time, in the `/oauth/token` response. A database dump cannot produce a valid token.	Access token: 1 hour. Refresh token: 30 days from its last use. It rotates on every refresh.
Upstream Auth0 tokens	Each connection gets its own Auth0 grant when you approve it, separate from your dashboard sign-in. 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.	GrainQL refreshes the Auth0 access token before it expires. If Auth0 rejects the refresh, GrainQL revokes the connection, and the client asks you to reconnect.
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. GrainQL 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, 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, the number of selected workspaces, or “All workspaces”. 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, MCP clients.
Click Revoke on the connection.
Confirm in the dialog. GrainQL 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 GrainQL 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

At consent you choose All workspaces in my account or Select workspaces.

All workspaces in my account: each tool call names the workspace it reads. GrainQL checks your membership of that workspace on every call, so the connection covers workspaces that you join later and loses a workspace as soon as you leave it.
Select workspaces: the session covers only the workspaces that you tick. A tool call for any other workspace fails with 403. If you tick one workspace, tools use it without a workspace argument. To change the list, connect again.
Every tool call checks membership again. A user who is removed from a tenant loses MCP access to it on the next tool call of the client.

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 GrainQL, 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

Security and scopes

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