Skip to main content

​
What this does

MCP bot authentication lets an approved non-human identity connect to LoopIQ MCP without an interactive user sign-in. Use it for scheduled agents, CI jobs, release checks, evidence collection, and other organization-managed automations. Bot authentication does not replace human sign-in. People continue to authenticate through ScrambleID OAuth. Bots use a separate client ID and client secret to obtain short-lived tokens that are valid only for the LoopIQ MCP resource.

​
How LoopIQ protects bot access

Each bot is:
  • associated with one LoopIQ organization
  • linked to an immutable ScrambleID bot subject
  • owned by the organization administrator who registered it
  • restricted to approved MCP scopes
  • issued short-lived, resource-bound access tokens
  • subject to the same permission, approval, and audit controls as other MCP callers
LoopIQ stores only a salted hash of the client secret. The original secret is displayed once when the bot is registered or its secret is rotated.

​
Before you begin

You need:
  • an organization administrator role in LoopIQ
  • the correct organization selected in LoopIQ
  • a bot identity created in ScrambleID
  • the bot’s immutable ScrambleID subject (sub)
  • an approved secret manager for storing the client secret
Do not use a person’s ScrambleID subject for a bot. Do not place a client secret or access token in source control, browser code, prompts, screenshots, tickets, or shared documents.

​
Register a bot

  1. In LoopIQ, open Organization Settings.
  2. Select MCP Bots.
  3. Confirm that the expected organization is active.
  4. Select Register Bot.
  5. Enter a descriptive Display name, such as Release evidence bot.
  6. Optionally enter the ScrambleID bot username.
  7. Enter the immutable ScrambleID bot subject (sub).
  8. Review Allowed MCP scopes.
  9. Select Register Bot.
  10. Copy the generated client ID and client secret immediately.
  11. Store the client secret in your organization’s approved secret manager.
The client secret cannot be displayed again. If it is lost, rotate it and update the automation that uses it.

​
Choose bot scopes

mcp:tools:read allows the bot to discover, read, and query MCP tools within its organization and permissions. It is required and is the recommended default. mcp:tools:write allows the bot to invoke mutating tools when the organization has enabled that scope. Write access does not bypass LoopIQ permissions, governed approvals, tenant isolation, or audit controls. Use the least privilege needed. Start with read-only access and add write access only for a reviewed automation with a named owner.

​
Generate a short-lived token in LoopIQ

Use this option for a temporary connection test or an approved manual diagnostic.
  1. Open Organization Settings and select MCP Bots.
  2. Find the registered bot.
  3. Confirm that its status is Active and its scopes are correct.
  4. Select Generate 10-minute token.
  5. Select Copy token.
  6. Use the token only with https://ai.loopiq.com/mcp.
  7. Remove the token from the client after the test.
The token expires automatically and cannot be used for another resource.

​
Request tokens from an automation

Production automations should request a fresh token instead of storing a generated access token. Use:
  • Token endpoint: https://ai.loopiq.com/token
  • MCP resource: https://ai.loopiq.com/mcp
  • Grant type: client_credentials
  • Authentication method: client_secret_basic or client_secret_post
Example using HTTP Basic authentication:
The response contains an access_token, expires_in, scope, and resource. Send the access token to the MCP endpoint as a bearer token:
Never log the client secret or complete access token. Refresh the token before it expires and discard the previous token.

​
Rotate a bot secret

Rotate the secret if it is lost, exposed, copied to an unapproved location, or due under your credential-rotation policy.
  1. Open Organization Settings and select MCP Bots.
  2. Find the bot.
  3. Select Rotate secret.
  4. Confirm the rotation.
  5. Copy the new secret and store it securely.
  6. Update the automation’s secret reference.
  7. Test the automation with a newly requested token.
Rotation immediately invalidates the previous secret and tokens issued under the previous credential version.

​
Disable or re-enable a bot

Select Disable to stop a bot from receiving or using tokens. Disable a bot when its automation is retired, its owner changes, or suspicious activity is under review. Select Enable only after confirming the bot identity, owner, scopes, and credential storage remain valid. If credential exposure is possible, rotate the secret before re-enabling the bot.

​
Review bot activity

The registered-bot list shows its status, ScrambleID subject, client ID, scopes, and last-used time. Use these details with LoopIQ audit history to confirm:
  • which bot performed an action
  • which organization and human owner were associated with it
  • which scopes were granted
  • when credentials or tokens were issued or rotated
  • whether a governed write action was approved

​
Troubleshooting

​
invalid_client

Confirm the client ID and secret are current, the bot is active, and the automation did not retain a secret that was rotated.

​
invalid_target

Set the token request’s resource exactly to https://ai.loopiq.com/mcp.

​
invalid_scope

Request only scopes displayed for the bot in LoopIQ. An organization administrator must explicitly grant any additional scope.

​
The token is expired

Request a new token through the client-credentials flow. Do not increase the lifetime or store an expired access token for reuse.

​
A read request works but a write request fails

Confirm the bot has mcp:tools:write, the owner and organization permissions allow the operation, and any required approval has been completed. Write scope alone does not authorize every action.

​
The bot sees the wrong organization

Disable the bot immediately. Confirm it was registered while the correct organization was selected and that its ScrambleID subject was not reused. Bot identities cannot cross organization boundaries.