Skip to main content
For an introduction to what the MCP server does and the controls it enforces, see the MCP Server overview.

​
Prerequisites

​
Endpoint

The MCP server is mounted at: 
https://<your-gateway>/api/mcp
Two authentication methods are supported — a Bearer token (always available) and OAuth 2.0 (must be enabled by an administrator). Both result in the agent acting as the authenticated user with the same RBAC, masking, guardrails, and review controls. See the authentication overview for how each method works.

​
Add the MCP Server to Your Client

Configure your MCP client to point at your gateway. The exact format varies by client. With OAuth enabled (the client negotiates the token automatically): 
{
  "mcpServers": {
    "hoop": {
      "url": "https://<your-gateway>/api/mcp"
    }
  }
}
On first connect, the client opens a browser window to complete the OAuth flow against your IdP (Google, Okta, Azure, etc., depending on your gateway configuration). With a Bearer token (works without OAuth being enabled): 
{
  "mcpServers": {
    "hoop": {
      "url": "https://<your-gateway>/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}
Use the token from hoop login or any valid Hoop API token.

​
Enabling OAuth via the CLI

OAuth on the /api/mcp endpoint is off by default and is managed by an administrator with the hoop admin mcp auth command group. When enabled, the endpoint accepts JWTs issued by the gateway’s configured OIDC issuer in addition to regular Hoop bearer tokens — so existing Bearer-token clients keep working. When enabled, discovery metadata is published at: 
https://<your-gateway>/.well-known/oauth-protected-resource/api/mcp
Most MCP clients (Claude Code, Cursor, Devin) detect this metadata and handle the OAuth flow without manual configuration — you only need to provide the /api/mcp URL.
These commands require an authenticated admin session (run hoop login first as an admin user).

​
Enable OAuth

hoop admin mcp auth enable
Optional flags let you override the defaults at the same time: 
hoop admin mcp auth enable \
  --resource-uri https://<your-gateway>/api/mcp \
  --groups-claim groups
FlagDefaultPurpose
--resource-uri<api-url>/api/mcpCanonical RFC 8707 audience binding. Inbound JWTs must carry this value as the aud claim.
--groups-claimgroupsThe JWT claim from which user groups are extracted.

​
Check current status

hoop admin mcp auth status
Prints the current state, resource URI, and groups claim: 
MCP OAuth Status:
  State:        enabled
  Resource URI: https://<your-gateway>/api/mcp
  Groups Claim: groups

​
Update configuration without toggling state

Use configure to change the resource URI or groups claim while leaving enabled/disabled as-is: 
hoop admin mcp auth configure --groups-claim cognito:groups
You must pass at least one of --resource-uri or --groups-claim.

​
Disable OAuth

hoop admin mcp auth disable
After this, /api/mcp accepts only Hoop bearer tokens. Any MCP client that was relying on the OAuth flow will need to switch to the Authorization: Bearer <token> header.

​
First Calls

Once the client is connected, these are the recommended first tool calls:
1

Confirm identity

Ask the agent to call me_get. The response confirms which user the MCP session is acting as, the groups it belongs to, and whether it has admin or auditor privileges. This is the recommended first call in any session.
2

Discover what's available

Have the agent call connections_list (and optionally serverinfo_get for gateway version and license info). The agent now knows which databases, applications, and custom resources it can target.
3

Run a query

Use exec to run a command against a resource role. The response is one of the envelopes below.
The exec response is one of three envelopes the agent should handle explicitly:
statusMeaningWhat the agent does next
completedOutput is in the response. May include AI analysis.Use the output. Done.
failedCommand ran but exited non-zero.Inspect output and exit_code.
pending_approvalA review is required before the command can run.Call reviews_wait, then reviews_execute once status=APPROVED.
runningCommand is still running after a 50-second timeout.Poll sessions_get with the returned session_id.
For how the approval and long-running flows work, see The Approval Flow and Long-Running Operations in the overview.

​
Troubleshooting

​
unauthorized: missing auth context or missing access token

Check:
  1. If using OAuth, the MCP client completed the flow successfully and OAuth is enabled on the gateway
  2. If using a Bearer token, the Authorization: Bearer <token> header is being sent and the token has not expired
  3. The gateway URL points to /api/mcp exactly

​
OAuth flow does not start / metadata endpoint returns 404

OAuth for the MCP endpoint is off by default. Ask an administrator to enable it on the gateway (hoop admin mcp auth enable), or fall back to the Bearer token method in the meantime.

​
Incompatible auth server: does not support dynamic client registration

This message comes from the MCP client (Claude Code, Cursor, etc.), not from Hoop. The client discovered Hoop’s protected-resource metadata, followed the authorization_servers URL to your IdP (Okta, Azure AD, Google, Auth0, etc.), and found that the IdP does not expose a registration_endpoint — so the client cannot create itself an OAuth client on the fly via RFC 7591 Dynamic Client Registration. Hoop itself does not implement DCR; it only delegates authorization to your IdP. You have two ways to move forward:
  • Pre-register a static OAuth client in your IdP: If you need full OAuth, ask your IdP admin to create an OAuth client for the MCP client manually and configure that client with the resulting client_id / client_secret. Each IdP exposes this differently — for example, Okta calls it an “OIDC application”, Azure calls it an “App Registration”. Most IdPs that support DCR have it disabled by default for security reasons.
  • Use the Bearer token method: This skips OAuth entirely. Configure your MCP client with an Authorization: Bearer <token> header using a token from hoop login.
If your IdP does support DCR and you expected it to work, confirm that DCR is enabled in your tenant and that the IdP’s discovery document (/.well-known/openid-configuration at the issuer URL) advertises a registration_endpoint.

​
admin access required

The tool is gated to admin users. Ask an administrator to perform the action, or use a read-only equivalent.

​
connection not found or not accessible

Check:
  1. The connection name is correct (use connections_list to verify)
  2. The user has a resource role granting access to this connection
  3. If the connection is bound to access_control, the user is in one of the allowed groups

​
pending_approval never resolves

Check:
  1. A reviewer group exists and has at least one member who can approve
  2. The reviewer was notified (Slack/Teams integration is configured, or they’re checking the Web App)
  3. The agent is calling reviews_wait repeatedly after each timed_out=true

​
Agent disconnects on long queries

This is expected for executions over ~50 seconds. Ensure the agent handles status=running by polling sessions_get with the returned session_id, rather than treating it as an error.