Organization integration

Backend access to Grunt's MCP services with organization credentials, for developers and integration administrators

This guide covers backend access to Grunt's MCP services using organization credentials. It is for a service integration that operates without an interactively signed-in user.

Users connecting Claude or another assistant through Grunt sign-in should follow Connect and authenticate. They do not need an organization client for that workflow.

#Access and ownership

An administrator creates an integration client. The backend exchanges its client ID and secret for an access token, then uses that token to call Grunt's MCP service.

Assets created through this integration belong to the organization and are accessible to its other MCP clients. They are separate from user-owned assets and do not appear in a user's personal asset list. Organization credentials do not convert existing personal assets into organization assets.

#Prerequisites

Requirement	Purpose
Organization access and administrator permissions	Create the integration client in the Client Portal.
Backend secret store	Protect the client secret outside prompts, user devices and shared documents.
OAuth client-credentials implementation	Obtain access tokens and request replacements on expiry.
Compatible MCP implementation	Call the service over Streamable HTTP and handle its tools and responses.
Integration owner	Maintain credentials, application access and operational support.

See Plans and AI access for product access and Security and data for service controls.

References: Connect and authenticate and MCP server.

#Configure the integration

#Create the client

Open the organization's Integrations page in the Client Portal.
Select Create client.
Choose MCP server under Access.
Capture the one-time secret and store it in the integration backend's secret store.
Under MCP connection details, copy the MCP server URL, token endpoint, resource and scope for your environment. Retain these with the client ID in the integration configuration.

If the Integrations page is unavailable, check permissions and enablement with the organization administrator or Grunt support. Never put client secrets in assistant prompts or distribute them to ordinary assistant users.

#Obtain and use an access token

The hosted MCP endpoint is https://mcp.grunt.io/mcp, with production authorization at https://auth.grunt.io/. Use the token endpoint and exact resource copied from the Client Portal for your environment.

Request a token with the client_credentials grant, client ID, client secret, mcp.access scope and exact advertised resource. Send the returned access token as a bearer token when calling MCP. The scope includes creation, reading and updates; it is not a read-only grant.

The authentication guide provides token-request and tool-discovery examples. Use an MCP SDK to handle initialization and protocol negotiation, then use the current tool names and input schemas returned by the server.

Organization access tokens last five minutes. Use the returned expiry to request a replacement token. The client-credentials flow does not issue a refresh token.

#Verify the connection

Use sample data to discover tools, create an asset and inspect its values. Check that the asset belongs to the organization and that another authorized organization client can access it. Record the tested environment, configuration and date.

Complete the asset checks as well as token acquisition. If the integration supplies PowerPoint or web outputs, check those outputs separately.

References: Connect and authenticate and Tool reference.

#Credentials and operations

#Credential lifecycle

Integration credentials are created, rotated and revoked through the Client Portal. Keep a procedure for updating the backend secret store and checking dependent services after a credential change. Already-issued access tokens remain valid until they expire, at most five minutes.

Keep client secrets and access tokens out of application logs, support requests, screenshots and prompts. Token renewal is a backend responsibility; users should not have to refresh the service integration manually.

#Asset and link access

Revoking an integration credential does not withdraw an already distributed asset link. View links expose underlying data and have no automatic expiry; revoke a link through the Web App's link-management API when it is no longer needed. Sharing, deletion and offboarding are separate from service authentication.

See Security and data for sharing between users, processing locations, access controls, retention and deletion.

For timeouts or transient errors, check whether the asset was created or updated before retrying. Repeating a creation call can create another asset.

#Troubleshooting

Symptom	First check
Integrations page is missing	Organization role and MCP product enablement.
Token request fails	Environment, client ID/secret, scope and token-request configuration.
Calls later become unauthorized	Returned expiry, replacement-token acquisition and credential status.
Asset is missing	Organization ownership context and the integration identity used.
Tool fails after authentication	Tool discovery, current schema and the returned error/reference ID.

For support, include the endpoint, approximate UTC time, tool name and reference ID. Exclude tokens and secrets. Contact Grunt support.

References: Credential handling and troubleshooting and Sharing rules.