> ## 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. # Model Context Protocol (MCP) > Let your AI Agents interact with Opal by using our MCP server. As of May 26, 2026, Opal has moved to **self-hosted MCPs**. Any previously Gram-hosted MCPs are no longer maintained — please update your configurations accordingly. Opal hosts our own specialized [Model Context Protocol (MCP) servers](https://modelcontextprotocol.io/introduction) that allow your AI agents to interact with Opal through Opal's REST API. Self-hosted Opal deployments can host MCP servers as of version v1.1135.0. With these MCP servers, AI assistants can help you manage access through natural language. Natural language queries include *"Show me all users in the Engineering group."*, *"Create an access request for the Production database."*, *"What access changes happened to our AWS resources this week?"* Opal provides three specialized MCP servers, each designed for specialized end user or admin use cases. Enable self service by requesting access through our MCP. Manage user access through our MCP. Investigate access and audit changes with our MCP. ## Authentication Opal MCP servers support three ways to authenticate. **OAuth is recommended** for interactive clients: you sign in through your browser and Opal issues a short-lived token scoped to your account, so no long-lived secret is stored in your client config. Use an **API token** for scripts and other non-interactive clients. If you use Okta, AI agents can also connect on behalf of your users through **Okta Cross App Access**. ### OAuth OAuth support is in early beta and may change. If you hit issues, use an [API token](#api-token) instead. Most MCP clients discover and complete the OAuth flow automatically. Add the server URL **without** an `Authorization` header and trigger your client's sign-in step; your client will redirect you to Opal to approve access, then receive a scoped access token it refreshes for you. Opal uses the OAuth 2.1 authorization code flow with PKCE. Per-client commands are on each server's installation page. If your client asks you to configure OAuth manually, use these values: | Field | Value | | - | - | | Client ID | Find it under **User → Settings → OAuth Grants** | | Resource / audience | Read the `resource` value from your server's protected-resource metadata at `/.well-known/oauth-protected-resource/` (e.g. `https://app.opal.dev/.well-known/oauth-protected-resource/mcp/end-user`) | | Server URL | The MCP endpoint you're connecting to, e.g. `https://app.opal.dev/mcp/end-user` | Opal uses a single pre-registered public client and does not support Dynamic Client Registration. Find your **Client ID**, and review or revoke the tokens issued to your account, in Opal under **User → Settings → OAuth Grants** (`app.opal.dev/user/settings/oauth-grants`). #### Scopes Opal's MCP OAuth server supports two scopes: | Scope | Grants | | - | - | | `mcp` | Full access — the resolved user's complete RBAC permissions, read and write. This is the highest scope level. | | `mcp:readonly` | Read-only access — every write path (mutating MCP tools, GraphQL mutations, unsafe REST methods) is rejected. | Scopes are additive, so requesting both together still grants full access — request `mcp:readonly` on its own if you want a read-only session. #### Refresh tokens (`offline_access`) Request the `offline_access` scope to receive a refresh token alongside your access token, so your client can renew access silently instead of prompting you to sign in again. Opal doesn't issue refresh tokens by default. An admin must enable them under **Settings → Authentication → MCP OAuth refresh tokens**, choosing **No one** (default), **Admins only**, or **Everyone**. If refresh tokens aren't enabled for your account, `offline_access` is dropped from the granted scope and you'll receive an access token only, with no refresh token. Access tokens default to a 1-hour lifetime, admin-configurable from 1 minute up to 24 hours under **MCP OAuth token lifetime**. Refresh tokens default to 30 days, admin-configurable from 1 day up to 365 days under **MCP OAuth refresh token lifetime**. Each time a refresh token is used, Opal rotates it — issuing a new access/refresh token pair and invalidating the old one. Reusing an already-rotated refresh token is treated as a sign of theft and notifies your organization's admins. #### Connecting from a platform (Databricks, Glean, and similar) Some platforms — Databricks, Glean, and similar tools that broker connections to external services — let you register one of Opal's MCP servers as an external tool through their own OAuth connection UI, rather than through an MCP client's built-in OAuth discovery. Since these platforms have you configure OAuth manually instead of performing full MCP discovery, a few settings need to be set explicitly: 1. **Allowlist the platform's OAuth callback URL.** In Opal, go to **Settings → Authentication → MCP OAuth callback URLs** and add the platform's callback URL under **Custom callback URLs**. For Databricks, this is `https:///login/oauth/http.html`; check your platform's own documentation for its equivalent. 2. **Use OAuth User-to-Machine (per-user) authentication**, if your platform distinguishes between OAuth types. Opal's OAuth broker only supports the interactive authorization-code-with-PKCE flow — there's no machine-to-machine/client-credentials support. 3. **Set the credential exchange (or client authentication) method to send the client ID in the request body**, not in an `Authorization` header, if your platform asks. Opal's token endpoint reads `client_id` from the request body. 4. **Client Secret doesn't apply.** Opal's OAuth client is a public client with no secret (see the note above) — leave this field blank, or enter a placeholder if your platform requires a non-empty value. 5. **If your platform asks for a resource or audience value**, use the value from this server's protected-resource metadata (see the table above). Opal also accepts a request that omits this value entirely, so it's fine to leave it blank if your platform has no field for it. 6. **Register the MCP server as a tool in your platform.** Setting up the OAuth connection isn't enough on its own — most platforms require a separate step to register or enable the MCP server as a usable tool before agents can call it. 7. **If your platform asks you to choose a transport protocol, choose Streamable HTTP.** Some platforms, like Glean, let you pick between SSE and Streamable HTTP when registering the MCP server — Opal's MCP servers support Streamable HTTP; SSE is not supported. Register Opal as an external MCP server in Unity Catalog: 1. Go to **Catalog → Connections → Create connection**, and choose type **HTTP**. 2. Set the server URL to one of Opal's MCP endpoints, e.g. `https://app.opal.dev/mcp/end-user` (swap in `/mcp/admin-user-provisioning` or `/mcp/admin-auditing` for the other servers). 3. Choose authentication **OAuth U2M per-user**, with OAuth provider **Manual configuration**: * Authorization endpoint: `https://app.opal.dev/authorize` * Token endpoint: `https://app.opal.dev/token` * Client ID: your value from **User → Settings → OAuth Grants** * Client secret: not used — leave blank or use a placeholder * Credential exchange method: **body\_only** 4. Log in to complete the OAuth flow, then go to **AI Gateway → MCPs → Register MCP Server** and select this connection so its tools become available to agents. See Databricks' [Register an external MCP server](https://docs.databricks.com/aws/en/ai-gateway/register-mcp-service) documentation for more detail. The steps above — allowlisting the callback URL, per-user OAuth, sending the client ID in the request body, no client secret, then registering the tool — apply generally. Check your platform's own documentation for the equivalent of each step. ### Okta Cross App Access Okta Cross App Access is in limited beta. Contact Opal support to enable it for your organization. If your organization uses Okta, AI agents registered in your Okta tenant can connect to Opal's MCP servers on behalf of your users without an interactive sign-in. See [Okta Cross App Access](/docs/mcp/okta-cross-app-access) for setup. ### API token [Create an API Token](/reference/authentication#using-the-api-with-personal-access-tokens) in your Opal environment and pass it to your client as an `Authorization: Bearer ${OPAL_API_TOKEN}` header, as shown in the installation steps for each server. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.