Skip to main content

​
What You’ll Accomplish

Hoop ships a built-in Model Context Protocol server that exposes the gateway as a set of tools an AI agent can call. Point Claude Code, Cursor, Devin, or any MCP-compatible client at it and the agent inherits the same controls a human user gets:
  • Run queries and commands against resource roles without ever handling credentials
  • Trigger and wait for human approvals before sensitive actions execute
  • Inspect schemas, sessions, and AI risk analysis from inside the agent’s loop
  • Manage resource roles, guardrails, data masking, and review rules — gated by admin roles
Every tool call goes through the same authorization, data masking, guardrails, and review gates as the rest of Hoop. The MCP server does not bypass any of them.

​
How It Works

1

Agent connects

The MCP client authenticates against the gateway’s OAuth endpoint and opens a streamable HTTP session at /api/mcp.
2

Agent calls a tool

The agent invokes a tool (for example exec to run a query, or connections_list to discover what’s available).
3

Gateway enforces policy

The gateway resolves the user’s identity, checks resource roles, applies data masking and guardrails, and triggers reviews when required — exactly as it does for the CLI and Web App.
4

Agent receives a structured response

Tool results come back as JSON envelopes with explicit status fields (completed, pending_approval, running, failed) so the agent can decide what to do next.

​
Endpoint and Authentication

The MCP server is mounted at: 
https://<your-gateway>/api/mcp
Two authentication methods are supported. Pick whichever your client makes easier — both result in the agent acting as the authenticated user with the same RBAC, masking, guardrails, and review controls.

​
Option A: Bearer Token (always available)

Pass an existing Hoop access token in the standard Authorization header: 
Authorization: Bearer <token>
This is the simplest path for clients that don’t yet implement the MCP OAuth flow, or for scripted setups where the token is already on hand. Any token that works against the Hoop API works here — for example, the one issued by hoop login.

​
Option B: OAuth 2.0 (must be enabled)

Hoop also implements the MCP authorization spec so MCP clients can negotiate access automatically. 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.
OAuth for the MCP endpoint is off by default and must be enabled by an administrator on the gateway before clients can use it. Until it’s enabled, use the Bearer Token method above. See the configuration guide for the hoop admin mcp auth commands.
Admin-only tools (creating connections, managing guardrails, deleting rules, etc.) are rejected for non-admin users with a clear admin access required error. Read tools follow the same RBAC rules as the Web App.

​
The Approval Flow

When a resource role requires review, exec returns status=pending_approval with a review_id and review_url. The agent should:
1

Notify the user

Surface the review_url so a reviewer can approve in Slack, Teams, or the Web App.
2

Long-poll the review

Call reviews_wait with the review_id. It blocks for up to 5 minutes (default 60 seconds) and returns when the review reaches a terminal status (APPROVED, REJECTED, REVOKED, EXECUTED). If it times out without a decision, the response carries timed_out=true — call again to keep waiting.
3

Execute the approved query

Once status=APPROVED, call reviews_execute with the same review_id. This runs the originally submitted query — the reviewer’s decision is final, and the agent cannot drift from what was approved.
This pattern lets autonomous agents safely operate against sensitive resources: the human reviewer is always in the loop for anything that matches a review rule, and the agent simply waits for the answer.

​
Tool Highlights

The MCP server exposes ~50 tools organized by area. The most commonly used ones:

​
Identity and Discovery

ToolPurpose
me_getAuthenticated user’s profile, groups, admin/auditor flags
serverinfo_getGateway version, auth method, license info
connections_listList connections accessible to the user, with optional filters
connections_getGet a single connection by name or ID

​
Execution

ToolPurpose
execRun a one-shot query or command against a connection. Mirrors hoop exec. Returns completed, pending_approval, or running envelope.
connection_databasesList databases on a Postgres / MySQL / MSSQL / MongoDB connection
connection_tablesList tables in a database
connection_columnsList columns of a table with their types

​
Reviews (Approvals)

ToolPurpose
reviews_listList all reviews for the organization
reviews_getGet a single review by ID or session ID
reviews_waitLong-poll a review until it reaches a terminal status. Returns timed_out=true after the timeout — call again to keep waiting.
reviews_executeRun a query that was blocked on an approved one-time review
reviews_updateApprove, reject, or revoke a review (requires reviewer group membership)

​
Sessions and Audit

ToolPurpose
sessions_listList sessions with filters (user, connection, date range, review status). Max 100 per page.
sessions_getSession metadata by ID
sessions_get_contentInput script and stdout/stderr output. Owner or admin/auditor only.
sessions_get_analysisHoop’s AI analysis: risk level, title, explanation, action
sessions_wait_analysisLong-poll until AI analysis is generated (it runs asynchronously after a session ends)

​
Administration (admin role required)

ToolPurpose
connections_create / connections_update / connections_deleteManage connections
guardrails_*Manage guardrail rules
datamasking_rules_*Manage data masking rules
access_control_set / access_control_unset / access_control_get / access_control_listRestrict connections to specific user groups
access_request_rules_*Manage approval workflows for connections
runbook_rules_*Manage allowed runbooks per group/connection
usergroups_*Manage user groups
users_list / users_getRead user directory
Some admin tools (data masking, access request rules) are limited to 1 rule on the OSS license. Upgrade for unlimited rules and additional features.

​
Long-Running Operations

MCP clients tear down idle streams after roughly 60–120 seconds. Hoop accommodates this with two complementary patterns:
  • Bounded long-poll. reviews_wait and sessions_wait_analysis accept a timeout_seconds argument (default 60, max 300). When the timeout elapses without a terminal state, the response carries timed_out=true and the agent re-calls to continue waiting. The server sends MCP-level pings every 30 seconds to keep the connection warm.
  • Async handoff. exec and reviews_execute return status=running with a session_id after a 50-second internal timeout. The execution continues in the background; the agent polls sessions_get to retrieve the final result.
Agents should always handle timed_out=true and status=running explicitly rather than treating them as errors.

​
Security Model

The MCP server enforces the same controls as every other Hoop interface:

Authorization

Every tool resolves the caller’s user, organization, groups, and resource roles. Cross-org access is impossible — queries are always org-scoped.

Data Masking

Configured masking rules apply to exec output before it reaches the agent. The model never sees raw PII or secrets.

Guardrails

Input and output guardrails block or modify content before the agent receives it. Same rules as the CLI.

Reviews

Resource roles with review rules cannot be executed without human approval. The agent gets pending_approval and must wait.

Audit

Every exec creates a session row, records the input, and runs AI analysis. Sessions are queryable via sessions_* tools and exportable via webhooks/SIEM.

Secrets Isolation

Connection secrets are never returned by connections_list. connections_get only includes them for admin users.

​
Best Practices

Start with me_get

Always confirm which identity the MCP session is acting as before doing anything sensitive.

Handle every envelope

Don’t assume exec returns output — branch on status for pending_approval and running.

Use schema tools first

connection_databases → connection_tables → connection_columns lets the agent ground queries in real schemas instead of guessing.

Pair with review rules

Configure review rules on sensitive resource roles so agent-initiated actions are gated by human approval.
Ready to connect a client? The MCP Server configuration guide covers adding the server to your client, enabling OAuth via the CLI, your first tool calls, and troubleshooting.

​
Next Steps

Claude Code Connection

Proxy Claude Code’s API traffic through Hoop for end-to-end AI safety

Access Requests

Configure review rules so agent actions require human approval

Guardrails

Define deterministic rules that block dangerous queries before they reach the connection

Live Data Masking

Redact PII and secrets in query output before the agent sees them