Skip to main content

Connect ToolHive to an enterprise identity provider

Connecting your corporate identity provider to ToolHive lets your teams access MCP tools using their existing credentials and group memberships. This guide covers the setup using a Virtual MCP Server (vMCP) with its embedded OAuth 2.0 Authorization Server, which brokers authentication between MCP clients and your IdP and enforces access control through Cedar policies.

Prerequisites​

  • Kubernetes cluster with the ToolHive operator installed
  • kubectl access to your target namespace
  • Admin access to your identity provider
  • A publicly reachable URL for your VirtualMCPServer (the embedded auth server needs a callback URL that your IdP can redirect to)

Choose your identity provider​

Follow the guide for your IdP to complete the full setup and deployment:

  • Microsoft Entra ID - uses App Roles for group-based access control, with the roles claim in access tokens
  • Okta - uses Okta Groups and a custom authorization server, with the groups claim in access tokens

For other OIDC-compliant providers, see vMCP authentication.

Single backend without vMCP?

If you only need to authenticate users to a single MCPServer (no aggregation, no embedded auth server), see the Role-based authorization with Okta tutorial. It uses Okta as the worked example, but the pattern applies to any OIDC provider.

One application per VirtualMCPServer​

Register a dedicated IdP application for each VirtualMCPServer. Do not reuse an existing app registered for other services (Grafana, Flux, Registry, etc.). A dedicated registration gives each vMCP its own audience and credentials, preventing tokens issued for one vMCP from being accepted by another.

Next steps​