Your agent needs to read meetings out of Grain. Grain ships a hosted Model Context Protocol (MCP) server and a versioned REST API, and the two do not expose the same things. The MCP is where Grain's AI features live: semantic search across transcripts, deal health, coaching scorecards, clip creation. The API is where the plumbing lives: webhooks, uploads, downloads, sharing, workspace metadata. Pick wrong and you either lose the search quality your agent depends on or lose the event hooks your pipeline depends on. Here is how to choose, and how to avoid rebuilding auth when you change your mind.
Two objects are being compared. One is a hosted MCP endpoint that Grain operates and updates on its own schedule. The other is a date-versioned REST API that you call directly with a bearer token.
Grain launched its official remote MCP server on June 18, 2025, and it is available to every Grain plan. The endpoint is hosted by Grain; there is nothing to install or run. Authentication is OAuth: the first connection opens a browser, the user signs in to Grain and approves access, and the server holds that grant for future sessions. The server supports Dynamic Client Registration (DCR), which is why no client ID or secret is required to connect.
Grain's own quick-start page lists a smaller tool set than the server currently exposes. Release notes from May 2026 added clip creation and bulk tagging, and July 2026 added smart topics and workspace management tools. Scalekit's connector reflects the live server at 41 tools.
Deal and coaching tools are restricted to Business and Enterprise plans; Free and Starter users receive an error when calling them. The server also ships nine MCP Prompts for structured reports such as voice-of-customer, pipeline health, and SPICED or MEDDICC deal analysis. Grain has flagged mcp-remote as a soon-to-be-deprecated connection method.
The Grain public API v2 lives under api.grain.com/_/public-api/v2. It exposes recordings (list, get, transcript in JSON, TXT, VTT, and SRT, download, upload, update title, tags, sharing to users and teams), hooks (create, list, delete across ten event types), and workspace metadata (users, teams, meeting types). Each request needs an Authorization: Bearer header and a Public-Api-Version header set to 2025-10-31, the only supported version.
Three credential types work: a Personal Access Token (PAT), a Workspace Access Token (WAT), or an OAuth 2.0 access token obtained via Authorization Code with PKCE. Rate limit is 300 requests per minute per token. The v1 beta API is sunset in September 2026.
Scalekit maintains both surfaces as separate connectors. The Grain connector wraps the REST API with 19 prebuilt tools using bearer token auth. The Grain MCP connector wraps the hosted MCP server with 41 tools using OAuth with DCR. Both sit behind the same connected account and execute_tool interface, which is the point of the rest of this article.
Four dimensions matter: what the agent can do, how it authenticates, what you own in production, and which scenarios favor which path. Grain is unusual in this series because the MCP surface is not a subset of the API. It is a different product surface.
The table below maps agent-relevant capabilities across both paths. Tool names in the MCP column are the Scalekit connector names, which prefix the server's native names with grainmcp_.
The gap that matters most for meeting-intelligence agents is search. The API filters recordings by title substring, date range, team, meeting type, and participant scope. It does not search transcript content. The MCP's grainmcp_search_in_transcripts runs hybrid keyword and semantic retrieval over segmented transcript chunks and returns matching segments grouped by meeting, so the agent never loads a full transcript to find one quote. A pricing-objection agent built on the API has to page through recordings and scan transcripts itself. The same agent on MCP makes one call.
The MCP has no event surface. If your agent should react when a recording finishes processing, a clip is created, or an upload completes, that requires the API's hooks. The MCP also cannot upload, download, retitle, or share individual recordings. Those are write operations on the recording object itself, and Grain has kept them on the API. An archival pipeline that pulls SRT transcripts and MP4 files into a data lake is an API workload, full stop.
Auth is where the two paths diverge most sharply for anyone running agents without a user present.
The hosted MCP server requires a browser-based OAuth consent flow. There is no API key fallback. DCR means the MCP client registers itself, so you never obtain a client ID from Grain, but the user still has to be present to approve the grant. The resulting session is scoped to that user's Grain permissions: meetings they attended or have access to, deals linked to those meetings, and nothing from other workspaces. Grain's docs state this explicitly. What the user can't see, the agent can't see.
The API accepts a PAT, a WAT, or an OAuth 2.0 access token, all sent as Authorization: Bearer. They differ in scope and lifecycle:
To use OAuth you must request a client_id and client_secret from Grain manually and register a redirect URI prefix. There is no self-serve app registration.
Both paths require per-user credential isolation in a multi-tenant B2B agent. MCP's OAuth flow gives you a token per user. The API's OAuth flow gives you an access token and refresh token per user. In neither case does the path itself solve storage, rotation, or revocation. Grain's API access tokens expire in an hour. Grain's MCP grants persist until the user revokes them in Grain. Your agent has to know which state it is in before every call. Those are infrastructure problems regardless of which path you choose.
The production question is simple: what breaks, who notices, and who fixes it?
Grain owns the tool schemas, the endpoint normalization, the semantic index, and the plan gating logic. When Grain adds a tool, your agent sees it on the next tools/list without a redeploy. That is real leverage; the July 2026 smart topics tool appeared with zero work on the consumer side. What you still own: the OAuth token per user, detecting when a grant has been revoked, and keeping one user's session from being reused for another. MCP tool schemas are unversioned. A renamed parameter ships when Grain ships it.
You own everything. Request construction, Public-Api-Version header discipline, 300 requests per minute per token with 429 backoff using Retry-After, cursor pagination, hook endpoint reachability (Grain probes the URL and requires a 2xx on creation), token refresh before the one-hour expiry, and the hook payload handling itself. In exchange you get a date-versioned contract: 2025-10-31 behaves the same next quarter. For deterministic pipelines that is the more predictable dependency.
The two surfaces drift independently. Grain shipped tags and action items to the API in March 2026, uploads in January 2026, and MCP clips in May 2026. Nothing forces parity. If your agent needs both semantic search and webhooks today, you are already on both paths, and you are already carrying two credential types for the same user.
Grain agents tend to fall cleanly into one bucket or the other. The lists below are specific to Grain, not generic MCP advice.
Whichever path you pick, the day a second user connects Grain is the day the auth problem becomes real. This section names it without dressing it up.
A meeting-prep agent serving 40 account executives holds 40 Grain grants. On the MCP path those are 40 OAuth sessions that Grain can revoke individually and silently. On the API path those are 40 access tokens expiring hourly plus 40 refresh tokens that rotate on every use. If two threads refresh the same user's token concurrently, one of them ends up holding a dead refresh token and the agent fails on the next run. That race is not hypothetical; it is the standard failure mode described in how to handle token refresh for AI agents.
The shortcut is a single Workspace Access Token. It works in demos and does not survive production. Every action appears in Grain as the admin who minted the token, every user can reach every recording in the workspace, and revoking one user's access means rotating the credential for everyone. For a deeper treatment see access control for multi-tenant AI agents.
Scalekit's two Grain connectors handle the credential lifecycle for both paths. The MCP connector runs the OAuth and DCR flow, stores the grant per user, and injects it on every tool call. The API connector collects the bearer token per user through a hosted page, vaults it, and injects it the same way. Your agent code calls execute_tool with a user identifier and never sees a token on either path. The MCP vs API decision stops being an auth decision.
The pattern below is the same for both connectors: resolve the user, confirm their connected account is active, retrieve the tools they are authorized to call, then run the model loop. The examples use the Claude Messages API in Python for the MCP connector and TypeScript for the API connector, plus a LangChain adapter at the end.
In the Scalekit dashboard, go to AgentKit, then Connections, then Create Connection. Create one connection for Grain MCP (no client credentials needed; DCR handles registration) and, if you need the API surface, one for Grain. Note the connection names. The string you pass as connection_name in code must match the dashboard connection name exactly; a mismatch returns an empty tool list rather than an error. The examples use grainmcp and grain.
Install the SDKs:
Set SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, SCALEKIT_CLIENT_SECRET, and ANTHROPIC_API_KEY in .env. The Scalekit values are under Developers, then API Credentials.
Before any code, be clear about what list_scoped_tools returns. It is not the Grain MCP catalog. It is the set of tools the current user's connected account is authorized to call, filtered to the connection you name. For a user on a Starter plan that surface will not include deal or coaching tools that would fail anyway. Scoping the surface is the accuracy and cost lever: fewer tools in context means better tool selection and fewer tokens spent before the agent does any work.
The loop is the standard Claude tool-use pattern. Claude decides which Grain tool to call; your code executes it through execute_tool with the same identifier; the result goes back as a tool_result block. The loop ends when stop_reason is end_turn.
Change USER_IDENTIFIER and the same script runs against a different rep's Grain workspace with that rep's permissions. No token handling changed.
The API connector uses a bearer token instead of OAuth, but the code path is identical. When the connected account is not active, getAuthorizationLink returns a hosted page that collects the user's Personal Access Token instead of showing an OAuth consent screen. Scalekit picks the right flow from the connection type.
The tools this agent sees are the 19 API tools such as grain_hooks_list, grain_hook_create, grain_recordings_list, and grain_recording_transcript_text_get. Full schemas are on the Grain connector docs page.
If you are on LangChain, skip the schema conversion. The Python SDK's adapter returns StructuredTool objects already bound to the user's connected account, and execution routes through Scalekit the same way.
Google ADK, Vercel AI SDK, and Mastra examples follow the same shape and live in the code samples section of the docs.
The comparison above is honest about the fact that Grain's two surfaces will keep drifting. The argument for Scalekit is that the drift stops being your problem at the auth and observability layer.
Every execute_tool call against either Grain connector is logged with the user who authorized it, the connection, the tool name, and the outcome. When a CISO asks which agent pulled a transcript from a board meeting and under whose grant, the answer is a query, not a three-week log archaeology project. The failure taxonomy that logging needs to support is laid out in audit trails for agent auth; the product surface is the Auth Logs dashboard.
A meeting-prep agent rarely stops at Grain. It reads the calendar, checks the CRM, and posts to Slack. Handing it the full Grain MCP server plus the full Slack server plus the full HubSpot server is over a hundred tools in context, most of which it should never be allowed to call. Virtual MCP Servers solve this: you define one server per agent role declaring exactly which connections and which tools it exposes, and you get a static mcp_server_url.
Per-user isolation is handled by session tokens. Before each run you call create_session_token for that user, which mints a short-lived bearer scoped to that user's connected accounts with a default expiry of about one hour. One server definition serves every tenant; the identity is per run. A Grain summarizer might expose five tools out of 41. The agent cannot call grainmcp_update_my_settings because it was never given it. Setup is in set up and connect, and the design rationale is in when to use a Virtual MCP Server.
The rep who connects Grain MCP today for search and Grain API tomorrow for webhook-driven archival has two credentials in Grain's eyes and one connected account identity in yours. Scope is a function of identity, not connector configuration. Both connectors are included on the free tier, which covers 10,000 connected accounts. For adjacent build patterns see the sales call prep agent and the deal intelligence agent templates.
If your agent's job is to find and reason about what was said across many meetings, or to surface deal risk and coaching signals, build on Grain MCP. The semantic search and the intelligence tools do not exist anywhere else, and the OAuth grant gives you correct per-user scoping by default.
If your agent's job is to move recordings, transcripts, and media in or out of Grain, or to react when Grain produces something new, build on the Grain API. Hooks, uploads, downloads, and recording-level administration are API only, and the date-versioned contract is the safer dependency for a pipeline that runs unattended.
Most production Grain agents end up touching both: MCP for the interactive intelligence layer, API for the event-driven plumbing underneath it. That means two credential types per user on day one. The credential management problem is the same on both paths, and that is what needs production-grade infrastructure rather than another table in your database.
Browse the Grain connector docs, or see all connectors in the AgentKit documentation.
If you are wiring Grain into a production agent and hit a question this article did not answer, two places will get you an engineer quickly. Join the Scalekit Slack community to compare notes with other teams building on Grain, Granola, Gong, and Fathom. Or, if you need immediate help with a multi-tenant design or a Virtual MCP Server layout, use the talk to us page and pick a time.
