Connect and authenticate

The Grunt MCP Server uses Streamable HTTP and OAuth authentication. Connect with user sign-in for personal assets, or use organization credentials for a machine-to-machine (M2M) integration.

#Add the server to your client

https://mcp.grunt.io/mcp

#OAuth metadata

Clients can discover the server's protected resource metadata at:

https://mcp.grunt.io/.well-known/oauth-protected-resource

The response includes:

• resource
• authorization_servers
• scopes_supported

Production advertises the mcp.access scope. Read the metadata from the endpoint you use, then retrieve the authorization server's /.well-known/openid-configuration for its authorization and token endpoints. Production uses https://auth.grunt.io/.

Use the exact advertised resource value when requesting a token. For production, it is https://mcp.grunt.io/mcp. Staging or another environment can use a different resource. Identity scopes such as openid and email do not replace mcp.access.

#Connect with organization credentials

Use the OAuth client_credentials grant when your integration runs without a signed-in user.

curl --fail-with-body --request POST "$GRUNT_TOKEN_ENDPOINT" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$GRUNT_CLIENT_ID" \
  --data-urlencode "client_secret=$GRUNT_CLIENT_SECRET" \
  --data-urlencode "scope=mcp.access" \
  --data-urlencode "resource=$GRUNT_MCP_RESOURCE"

Access tokens currently last five minutes. Use the returned expires_in to schedule renewal. This grant does not issue a refresh token; request another access token with the client credentials when needed.

mcp.access covers the available chart and table creation, update, and read tools. There is no separate chart-write or asset-create scope. Public API access uses a different resource and token; do not combine Public API scopes with MCP access in one token.

Assets created with organization credentials belong to that organization and can be accessed by its other MCP clients. They do not automatically appear among a user's personal assets. Use an asset ID owned by the same organization when reading or updating it.

#Test an authenticated connection

Use an MCP SDK for normal connections so it handles initialization and protocol negotiation. With a valid access token, you can also inspect the current tool list directly. Set GRUNT_MCP_URL to your server URL and GRUNT_ACCESS_TOKEN to the returned access token:

curl --fail-with-body --request POST "$GRUNT_MCP_URL" \
  -H "Authorization: Bearer $GRUNT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

Use the exact tool name and inputSchema returned by this endpoint. For example, the bar-chart tool is create_or_update_bar_chart. See the tool reference for a complete tools/call request body. Send it to the same URL with the same headers.

#Troubleshooting

• Token request fails: confirm that the client and its secret are enabled and unexpired, that the client has MCP server access, and that scope is mcp.access. Use the exact resource and token endpoint for the target environment.
• MCP returns 401 Unauthorized: obtain a fresh access token and check its target resource. For user sign-in, reconnect and complete authorization.
• Reads work but chart or table creation reports an unknown tool or internal error: refresh tools/list and compare the exact tool name in your outgoing tools/call. Older names such as bar_chart and table are not aliases. Use create_or_update_bar_chart and create_or_update_table. This naming mismatch does not require an additional write scope.
• An asset cannot be read or updated: confirm that the asset belongs to the authenticated user or organization. Personal assets and organization assets have separate ownership.
• The tool reports invalid arguments: check the current inputSchema, including required properties and supported values.
• The server does not appear in your client: confirm that the client supports remote MCP servers over Streamable HTTP and your chosen authentication flow.
• A correctly named call still fails: send Grunt support the reference ID, MCP URL, approximate UTC time, and tool name. Do not send access tokens or client secrets. For timeouts or transient failures, check whether the asset was created or updated before retrying; repeating a creation call can create another asset.