> ## Documentation Index
> Fetch the complete documentation index at: https://help.loopiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage MCP bot access

## 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

<Warning>
  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.
</Warning>

## 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:

```bash theme={null}
curl --request POST https://ai.loopiq.com/token \
  --user "$LOOPIQ_MCP_CLIENT_ID:$LOOPIQ_MCP_CLIENT_SECRET" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "resource=https://ai.loopiq.com/mcp" \
  --data-urlencode "scope=mcp:tools:read"
```

The response contains an `access_token`, `expires_in`, `scope`, and `resource`. Send the access token to the MCP endpoint as a bearer token:

```text theme={null}
Authorization: Bearer <short-lived-access-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.

## Related articles

* [Connect LoopIQ MCP clients](/ai-and-agents/connect-loopiq-mcp-clients)
* [Governed MCP actions, approvals, and audit](/ai-and-agents/governed-mcp-actions-approvals-and-audit)
* [Build a custom agent with LoopIQ MCP](/ai-and-agents/build-a-custom-agent-with-loopiq-mcp)
* [MCP tool and action catalog](/ai-and-agents/mcp-tool-and-action-catalog)
* [Manage roles, permissions, and access](/administration/manage-roles-permissions-and-access)