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

# Admin Auditing MCP Server

> Let admins audit access with Opal using our Admin Auditing MCP server.

Opal's admin auditing MCP provides a set of tools that enables admins to use AI agents to view Opal events and syncs to investigate access and audit changes. Use cases include:

* Investigate historical access patterns and anomalous access
* Audit changes in organizational structure or role assignments
* Review sync errors and propagation status
* Monitor access requests and approvals
* Track user access reviews and compliance activities

## 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/admin-auditing`. 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-admin-auditing https://app.opal.dev/mcp/admin-auditing
> ```
>
> ```
> claude mcp login opal-admin-auditing
> ```
>
> 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-admin-auditing https://app.opal.dev/mcp/admin-auditing --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-admin-auditing": {
>       "transport": "http",
>       "url": "https://app.opal.dev/mcp/admin-auditing"
>     }
>   }
> }
> ```
>
> 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-admin-auditing": {
>       "transport": "http",
>       "url": "https://app.opal.dev/mcp/admin-auditing",
>       "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-admin-auditing": {
>       "httpUrl": "https://app.opal.dev/mcp/admin-auditing"
>     }
>   }
> }
> ```
>
> **API token:** add an `Authorization` header instead.
>
> ```
> {
>   "mcpServers": {
>     "opal-admin-auditing": {
>       "httpUrl": "https://app.opal.dev/mcp/admin-auditing",
>       "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/admin-auditing`
> * **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 |
| - | - |
| `get_resource` | Retrieves a resource. |
| `search_resources` | Searches for resources in your organization by name, resource type, or connection ID. |
| `get_sync_errors` | Returns a list of recent sync errors that have occurred since the last successful sync. |
| `get_resource_visibility` | Gets the visibility of this resource. |
| `get_uar` | Retrieves a specific UAR. |
| `get_uars` | Returns a list of `UAR` objects. |
| `get_on_call_schedules` | Returns a list of `OnCallSchedule` objects. |
| `get_message_channels` | Returns a list of `MessageChannel` objects. |
| `get_tags` | Returns a list of tags created by your organization. |
| `get_sessions` | Returns a list of `Session` objects. |
| `get_user_tags` | Returns all tags applied to the user. |
| `get_users` | Returns a list of users for your organization. |
| `get_resource_scoped_role_permissions` | Returns all the scoped role permissions that apply to the given resource. Only `OPAL_SCOPED_ROLE` resource type supports this field. |
| `list_resource_tags` | Returns all tags applied to the specified resources. |
| `get_resource_nhis` | Gets the list of non-human identities with access to this resource. |
| `get_resource_users` | Gets the list of users for this resource. |
| `get_nhis` | Returns a list of non-human identities for your organization. |
| `get_resource_reviewer_stages` | Gets the list of reviewer stages for a resource. |
| `get_resource_reviewers` | Gets the list of owner IDs of the reviewers for a resource. |
| `get_resource_message_channels` | Gets the list of audit message channels attached to a resource. |
| `list_requests` | Returns a paginated list of access requests across your organization. |
| `get_request` | Returns a request by ID. |
| `get_owner_users` | Gets the list of users for this owner, in escalation priority order if applicable. |
| `get_owners` | Returns a list of `Owner` objects. |
| `get_idp_group_mappings` | Returns the configured set of available `IdpGroupMapping` objects for an Okta app. |
| `get_group_users` | Gets the list of users for this group. |
| `get_group_reviewer_stages` | Gets the list of reviewer stages for a group. |
| `get_group_reviewers` | Gets the list of owner IDs of the reviewers for a group. |
| `get_group_visibility` | Gets the visibility of this group. |
| `get_events` | Returns a list of `Event` objects. |
| `search_groups` | Searches for groups in your organization by name or connection ID. |
| `get_group_containing_groups` | Gets the list of groups that the group gives access to. |
| `get_group_on_call_schedules` | Gets the list of on call schedules attached to a group. |
| `get_group_resources` | Gets the list of resources that the group gives access to. |
| `get_group_message_channels` | Gets the list of audit and reviewer message channels attached to a group. |
| `get_bundle_groups` | Returns a list of `Group` objects in a given bundle. |
| `get_bundle_visibility` | Gets the visibility of the bundle. |
| `get_bundle_resources` | Returns a list of `Resource` objects in a given bundle. |
| `get_apps` | Returns a list of `App` objects. |
| `get_configuration_templates` | Returns a list of `ConfigurationTemplate` objects. |
| `get_bundles` | Returns a list of `Bundle` objects. |

## Tool Parameters

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

> [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\_sync\_errors
>
> | Param | Type | Notes |
> | - | - | - |
> | `connection_id` | string | UUID of the connection to fetch sync errors for |
> | `resource_id` | string | UUID of the resource to fetch sync errors for |
> | `group_id` | string | UUID of the group to fetch sync errors for |
> | `limit` | integer | Maximum number of sync errors to return |
> | `include_dismissed` | boolean | Include sync errors that have been dismissed (default: false) |

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

> [accordion] get\_uar
>
> | Param | Type | Notes |
> | - | - | - |
> | `access_review_id` | string | required. UUID of the access review |

> [accordion] get\_uars
>
> | Param | Type | Notes |
> | - | - | - |
> | `status` | string | Optional status filter: STARTED or COMPLETED |
> | `search_query` | string | Optional search query to filter by name |
> | `limit` | integer | Maximum number of access reviews to return |

> [accordion] get\_on\_call\_schedules
>
> | Param | Type | Notes |
> | - | - | - |
> | `include_deleted` | boolean | Include deleted on-call schedules (default: false) |

> [accordion] get\_message\_channels
>
> | Param | Type | Notes |
> | - | - | - |
> | `include_deleted` | boolean | Include deleted message channels (default: false) |

> [accordion] get\_tags
>
> | Param | Type | Notes |
> | - | - | - |
> | `search_query` | string | Search query to filter tags by key or value |
> | `limit` | integer | Maximum number of tags to return (default: 100) |

> [accordion] get\_sessions
>
> | Param | Type | Notes |
> | - | - | - |
> | `resource_id` | string | required. UUID of the resource to list sessions for |
> | `user_id` | string | Optional UUID of the user to filter sessions by |

> [accordion] get\_user\_tags
>
> | Param | Type | Notes |
> | - | - | - |
> | `user_id` | string | required. UUID of the user |

> [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\_scoped\_role\_permissions
>
> | Param | Type | Notes |
> | - | - | - |
> | `resource_id` | string | required. UUID of the resource |

> [accordion] list\_resource\_tags
>
> | Param | Type | Notes |
> | - | - | - |
> | `resource_ids` | string\[] | required. UUIDs of resources to list tags for |

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

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

> [accordion] get\_nhis
>
> | Param | Type | Notes |
> | - | - | - |
> | `limit` | integer | Maximum number of NHIs to return (default 100) |

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

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

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

> [accordion] list\_requests
>
> | Param | Type | Notes |
> | - | - | - |
> | `entity_ids` | string\[] | List of UUIDs of resources 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] get\_request
>
> | Param | Type | Notes |
> | - | - | - |
> | `request_id` | string | required. UUID of the access request |

> [accordion] get\_owner\_users
>
> | Param | Type | Notes |
> | - | - | - |
> | `owner_id` | string | required. UUID of the owner |

> [accordion] get\_owners
>
> | Param | Type | Notes |
> | - | - | - |
> | `search_query` | string | Search query to filter owners by name |
> | `limit` | integer | Maximum number of owners to return |

> [accordion] get\_idp\_group\_mappings
>
> | Param | Type | Notes |
> | - | - | - |
> | `app_resource_id` | string | UUID of the app resource to filter mappings by |
> | `group_id` | string | UUID of the group to filter mappings by |

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

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

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

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

> [accordion] get\_events
>
> | Param | Type | Notes |
> | - | - | - |
> | `actor_user_id` | string | UUID of the actor (user) to filter events by |
> | `limit` | integer | Maximum number of events to return (default: 100, max: 1000) |

> [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\_containing\_groups
>
> | Param | Type | Notes |
> | - | - | - |
> | `group_id` | string | required. UUID of the member group to find containing (parent) groups for |

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

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

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

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

> [accordion] get\_bundle\_visibility
>
> | 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\_apps
>
> | Param | Type | Notes |
> | - | - | - |
> | `search_query` | string | Text search on app name |

> [accordion] get\_configuration\_templates
>
> | Param | Type | Notes |
> | - | - | - |
> | `admin_owner_id` | string | Optional UUID of the admin owner to filter templates by |

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


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