> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Connect AI agents to Hoop with the built-in Model Context Protocol server — every action stays under the same authorization, masking, guardrails, and review controls as a human session
## What You'll Accomplish
Hoop ships a built-in [Model Context Protocol](https://modelcontextprotocol.io) 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
The MCP client authenticates against the gateway's OAuth endpoint and opens a streamable HTTP session at `/api/mcp`.
The agent invokes a tool (for example `exec` to run a query, or `connections_list` to discover what's available).
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.
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:///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
```
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](https://modelcontextprotocol.io/specification/draft/basic/authorization) so MCP clients can negotiate access automatically. When enabled, discovery metadata is published at:
```
https:///.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](/setup/configuration/mcp-server-configuration#enabling-oauth-via-the-cli) 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:
Surface the `review_url` so a reviewer can approve in Slack, Teams, or the Web App.
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.
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
| Tool | Purpose |
| ------------------ | -------------------------------------------------------------- |
| `me_get` | Authenticated user's profile, groups, admin/auditor flags |
| `serverinfo_get` | Gateway version, auth method, license info |
| `connections_list` | List connections accessible to the user, with optional filters |
| `connections_get` | Get a single connection by name or ID |
### Execution
| Tool | Purpose |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `exec` | Run a one-shot query or command against a connection. Mirrors `hoop exec`. Returns `completed`, `pending_approval`, or `running` envelope. |
| `connection_databases` | List databases on a Postgres / MySQL / MSSQL / MongoDB connection |
| `connection_tables` | List tables in a database |
| `connection_columns` | List columns of a table with their types |
### Reviews (Approvals)
| Tool | Purpose |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `reviews_list` | List all reviews for the organization |
| `reviews_get` | Get a single review by ID or session ID |
| `reviews_wait` | Long-poll a review until it reaches a terminal status. Returns `timed_out=true` after the timeout — call again to keep waiting. |
| `reviews_execute` | Run a query that was blocked on an approved one-time review |
| `reviews_update` | Approve, reject, or revoke a review (requires reviewer group membership) |
### Sessions and Audit
| Tool | Purpose |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| `sessions_list` | List sessions with filters (user, connection, date range, review status). Max 100 per page. |
| `sessions_get` | Session metadata by ID |
| `sessions_get_content` | Input script and stdout/stderr output. Owner or admin/auditor only. |
| `sessions_get_analysis` | Hoop's AI analysis: risk level, title, explanation, action |
| `sessions_wait_analysis` | Long-poll until AI analysis is generated (it runs asynchronously after a session ends) |
### Administration (admin role required)
| Tool | Purpose |
| -------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `connections_create` / `connections_update` / `connections_delete` | Manage connections |
| `guardrails_*` | Manage guardrail rules |
| `datamasking_rules_*` | Manage data masking rules |
| `access_control_set` / `access_control_unset` / `access_control_get` / `access_control_list` | Restrict 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_get` | Read 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:
Every tool resolves the caller's user, organization, groups, and resource roles. Cross-org access is impossible — queries are always org-scoped.
Configured masking rules apply to `exec` output before it reaches the agent. The model never sees raw PII or secrets.
Input and output guardrails block or modify content before the agent receives it. Same rules as the CLI.
Resource roles with review rules cannot be executed without human approval. The agent gets `pending_approval` and must wait.
Every `exec` creates a session row, records the input, and runs AI analysis. Sessions are queryable via `sessions_*` tools and exportable via webhooks/SIEM.
Connection secrets are never returned by `connections_list`. `connections_get` only includes them for admin users.
***
## Best Practices
Always confirm which identity the MCP session is acting as before doing anything sensitive.
Don't assume `exec` returns output — branch on `status` for `pending_approval` and `running`.
`connection_databases` → `connection_tables` → `connection_columns` lets the agent ground queries in real schemas instead of guessing.
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](/setup/configuration/mcp-server-configuration) covers adding the server to your client, enabling OAuth via the CLI, your first tool calls, and troubleshooting.
## Next Steps
Proxy Claude Code's API traffic through Hoop for end-to-end AI safety
Configure review rules so agent actions require human approval
Define deterministic rules that block dangerous queries before they reach the connection
Redact PII and secrets in query output before the agent sees them