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

# End User MCP Server

> Let end users interact with Opal using our end user MCP server.

Opal's End User MCP provides a set of tools that enables end users to leverage AI agents to request access to Opal resources, groups, and bundles . Use cases include:

* Browse available resources, groups, and bundles
* Create access requests for yourself or as part of a workflow
* Check request status and view your current access
* Use in combination with other MCP servers (e.g., request access to Retool, then use Retool's MCP server to query data)

## Installation

> [!NOTE]
>
> **OAuth is the recommended way to connect.** The OAuth commands below sign you in to Opal in your browser — no stored secret. Find your Client ID under **User → Settings → OAuth Grants** (`app.opal.dev/user/settings/oauth-grants`); if your client asks for a resource or audience value, read it from this server's protected-resource metadata at `https://app.opal.dev/.well-known/oauth-protected-resource/mcp/end-user`. See [Authentication](https://docs.opal.dev/docs/mcp/overview.md#authentication) for details. To use an API token instead, [create one](https://docs.opal.dev/reference/authentication.md#using-the-api-with-personal-access-tokens) first.

> [!NOTE]
>
> Self-hosted Opal deployments can host MCP servers as of version v1.1135.0. If
> you run self-hosted, remember to replace [https://app.opal.dev](https://app.opal.dev) with your own
> domain.

> [tab] Claude Code
>
> **OAuth (recommended):** add the server with no `Authorization` header, then sign in.
>
> ```
> claude mcp add --transport http opal-end-user https://app.opal.dev/mcp/end-user
> ```
>
> ```
> claude mcp login opal-end-user
> ```
>
> Claude Code also prompts you to sign in the first time it calls a tool from this server. Check server status any time with `claude /mcp`.
>
> **API token:** pass the token as a header when you add the server.
>
> ```
> claude mcp add --transport http opal-end-user https://app.opal.dev/mcp/end-user --header "Authorization: Bearer ${OPAL_API_TOKEN}"
> ```
>
> To learn more, see Claude Code [documentation](https://code.claude.com/docs/en/mcp).

> [tab] Cursor
>
> **OAuth (recommended):** add the following to your `~/.cursor/mcp.json` file, with no `Authorization` header:
>
> ```
> {
>   "mcpServers": {
>     "opal-end-user": {
>       "transport": "http",
>       "url": "https://app.opal.dev/mcp/end-user"
>     }
>   }
> }
> ```
>
> Open **Cursor Settings → MCP**, and click **Needs login** next to the server to sign in through your browser.
>
> **API token:** add an `Authorization` header instead.
>
> ```
> {
>   "mcpServers": {
>     "opal-end-user": {
>       "transport": "http",
>       "url": "https://app.opal.dev/mcp/end-user",
>       "headers": {
>         "Authorization": "Bearer ${env:OPAL_API_TOKEN}"
>       }
>     }
>   }
> }
> ```
>
> Define your `OPAL_API_TOKEN`, and make sure you open Cursor from the same shell.
>
> ```
> export OPAL_API_TOKEN="secret"
> ```
>
> ```
> open -a Cursor
> ```
>
> To learn more, see Cursor [documentation](https://cursor.com/docs/mcp).

> [tab] Gemini CLI
>
> **OAuth (recommended):** add the following to your `~/.gemini/settings.json`, with no `Authorization` header, then follow the sign-in prompt on first use:
>
> ```
> {
>   "mcpServers": {
>     "opal-end-user": {
>       "httpUrl": "https://app.opal.dev/mcp/end-user"
>     }
>   }
> } 
> ```
>
> **API token:** add an `Authorization` header instead.
>
> ```
> {
>   "mcpServers": {
>     "opal-end-user": {
>       "httpUrl": "https://app.opal.dev/mcp/end-user",
>       "headers": {
>         "Authorization": "Bearer ${OPAL_API_TOKEN}"
>       }
>     }
>   }
> }
> ```
>
> To learn more, see Gemini [documentation](https://geminicli.com/docs/tools/mcp-server/).

> [tab] Other
>
> MCP is an open protocol supported by many other clients, and your specific client documentation can advise you how to connect. Key inputs:
>
> * Transport `http`
> * Endpoint `https://app.opal.dev/mcp/end-user`
> * **OAuth (recommended):** omit the `Authorization` header — most clients discover Opal's OAuth support automatically and prompt you to sign in.
> * **API token:** add the header `Authorization: Bearer ${OPAL_API_TOKEN}`.

## Available Tools

| Tool | Description |
| - | - |
| `search_resources` | Searches for resources in your organization by name, resource type, or connection ID. |
| `get_resource` | Retrieves a resource by ID. |
| `get_resource_reviewers` | Gets the list of owner IDs of the reviewers for a resource. |
| `get_resource_request_configurations` | Gets the request configurations for a resource, including requestability, auto-approval, MFA, and duration limits. |
| `get_resource_access_levels` | Gets the named access levels defined for a resource. |
| `search_groups` | Searches for groups in your organization by name or connection ID. |
| `get_group` | Returns a `Group` object. |
| `get_group_reviewers` | Gets the list of owner IDs of the reviewers for a group. |
| `get_group_request_configurations` | Gets the request configurations for a group, including requestability, auto-approval, MFA, and duration limits. |
| `get_group_access_levels` | Gets the named access levels defined for a group. |
| `list_requests` | Returns a paginated list of access requests across your organization. |
| `lookup_opal_user` | Looks up an Opal user by their email address to retrieve detailed profile, manager, and metadata information. |
| `get_users` | Returns a list of users for your organization. |
| `get_resource_users` | Gets the list of users for this resource. |
| `get_resource_nhis` | Gets the list of non-human identities with access to this resource. |
| `create_request` | Creates an access request for resources and/or groups. |
| `get_request` | Returns a request by ID. |
| `cancel_request` | Cancels a pending access request submitted by the authenticated requester. |
| `reviewer_approve_request` | Approves a pending access request on behalf of the authenticated reviewer. |
| `reviewer_deny_request` | Denies a pending access request on behalf of the authenticated reviewer. |
| `get_group_users` | Gets the list of users for this group. |
| `get_group_containing_groups` | Gets the list of groups that the group gives access to. |
| `get_group_resources` | Gets the list of resources that the group gives access to. |
| `get_apps` | Returns a list of `App` objects. |
| `get_bundles` | Returns a list of `Bundle` objects. |
| `get_bundle` | Returns a `Bundle` object. |
| `get_bundle_resources` | Returns a list of `Resource` objects in a given bundle. |
| `get_bundle_groups` | Returns a list of `Group` objects in a given bundle. |

## Tool Parameters

> [accordion] search\_resources
>
> | Param | Type | Notes |
> | - | - | - |
> | `name_filter` | string | required. Text search on resource name |
> | `resource_types` | string\[] | Optional: restrict results to these resource types |
> | `connection_ids` | string\[] | Optional: restrict results to these connection IDs |

> [accordion] get\_resource
>
> | Param | Type | Notes |
> | - | - | - |
> | `resource_id` | string | required. UUID of the resource to look up |

> [accordion] get\_resource\_reviewers
>
> | Param | Type | Notes |
> | - | - | - |
> | `resource_id` | string | required. UUID of the resource |

> [accordion] get\_resource\_request\_configurations
>
> | Param | Type | Notes |
> | - | - | - |
> | `resource_id` | string | required. UUID of the resource |

> [accordion] get\_resource\_access\_levels
>
> | Param | Type | Notes |
> | - | - | - |
> | `resource_id` | string | required. UUID of the resource |

> [accordion] search\_groups
>
> | Param | Type | Notes |
> | - | - | - |
> | `name_filter` | string | required. Text search on group name |
> | `connection_ids` | string\[] | Optional: restrict results to these connection IDs |

> [accordion] get\_group
>
> | Param | Type | Notes |
> | - | - | - |
> | `group_id` | string | required. UUID of the group to look up |

> [accordion] get\_group\_reviewers
>
> | Param | Type | Notes |
> | - | - | - |
> | `group_id` | string | required. UUID of the group |

> [accordion] get\_group\_request\_configurations
>
> | Param | Type | Notes |
> | - | - | - |
> | `group_id` | string | required. UUID of the group |

> [accordion] get\_group\_access\_levels
>
> | Param | Type | Notes |
> | - | - | - |
> | `group_id` | string | required. UUID of the group |

> [accordion] list\_requests
>
> | Param | Type | Notes |
> | - | - | - |
> | `entity_ids` | string\[] | List of UUIDs of users or groups to filter requests by |
> | `requester_ids` | string\[] | UUIDs of users who made the requests |
> | `target_user_ids` | string\[] | UUIDs of users the requests are for |
> | `search_query` | string | Search query to filter requests |
> | `start_date` | string | Filter requests created after this date (RFC3339 format) |
> | `end_date` | string | Filter requests created before this date (RFC3339 format) |
> | `show_pending_only` | boolean | Only show pending requests |
> | `cursor` | string | Opaque pagination cursor from previous response |
> | `limit` | integer | Maximum number of requests to return (default: 100, max: 1000) |

> [accordion] lookup\_opal\_user
>
> | Param | Type | Notes |
> | - | - | - |
> | `email` | string | required. The email address of the user to look up |

> [accordion] get\_users
>
> | Param | Type | Notes |
> | - | - | - |
> | `cursor` | string | Opaque pagination cursor from a previous response |
> | `page_size` | integer | Maximum number of users to return (default 100) |

> [accordion] get\_resource\_users
>
> | Param | Type | Notes |
> | - | - | - |
> | `resource_id` | string | required. UUID of the resource |

> [accordion] get\_resource\_nhis
>
> | Param | Type | Notes |
> | - | - | - |
> | `resource_id` | string | required. UUID of the resource |

> [accordion] create\_request
>
> | Param | Type | Notes |
> | - | - | - |
> | `reason` | string | required. Reason for the access request |
> | `resource_ids` | string\[] | UUIDs of resources to request access to |
> | `group_ids` | string\[] | UUIDs of groups to request access to |
> | `duration_minutes` | integer | Duration of access in minutes |
> | `target_user_id` | string | UUID of user to request access on behalf of (defaults to the requesting user) |

> [accordion] get\_request
>
> | Param | Type | Notes |
> | - | - | - |
> | `request_id` | string | required. UUID of the access request |

> [accordion] cancel\_request
>
> | Param | Type | Notes |
> | - | - | - |
> | `request_id` | string | required. UUID of the pending access request to cancel |

> [accordion] reviewer\_approve\_request
>
> | Param | Type | Notes |
> | - | - | - |
> | `request_id` | string | required. UUID of the access request to approve |
> | `comment` | string | Optional comment recorded with the approval |

> [accordion] reviewer\_deny\_request
>
> | Param | Type | Notes |
> | - | - | - |
> | `request_id` | string | required. UUID of the access request to deny |
> | `comment` | string | required. Comment explaining why the request is being denied |

> [accordion] get\_group\_users
>
> | Param | Type | Notes |
> | - | - | - |
> | `group_id` | string | required. UUID of the group |

> [accordion] get\_group\_containing\_groups
>
> | Param | Type | Notes |
> | - | - | - |
> | `group_id` | string | required. UUID of the member group to find containing (parent) groups for |

> [accordion] get\_group\_resources
>
> | Param | Type | Notes |
> | - | - | - |
> | `group_id` | string | required. UUID of the group |

> [accordion] get\_apps
>
> | Param | Type | Notes |
> | - | - | - |
> | `search_query` | string | Text search on app name |

> [accordion] get\_bundles
>
> | Param | Type | Notes |
> | - | - | - |
> | `search_query` | string | Text search on bundle name |

> [accordion] get\_bundle
>
> | Param | Type | Notes |
> | - | - | - |
> | `bundle_id` | string | required. UUID of the bundle |

> [accordion] get\_bundle\_resources
>
> | Param | Type | Notes |
> | - | - | - |
> | `bundle_id` | string | required. UUID of the bundle |

> [accordion] get\_bundle\_groups
>
> | Param | Type | Notes |
> | - | - | - |
> | `bundle_id` | string | required. UUID of the bundle |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.