--- title: Authenticate MCP clients with OAuth description: OAuth 2.1 lets MCP clients authenticate to the Agent Builder MCP server on behalf of a user, using short-lived tokens instead of static API keys. url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-client-oauth products: - Elastic Cloud Serverless - Elastic Observability - Elastic Security - Elasticsearch - Kibana applies_to: - Elastic Cloud Serverless: Preview --- # Authenticate MCP clients with OAuth The [Elastic Agent Builder MCP server](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-server) supports OAuth 2.1 as a way for MCP clients to authenticate on behalf of a user, alongside [API keys](/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-server#api-key-application-privileges). OAuth suits interactive, agentic use cases: instead of configuring a static, long-lived API key, a user connects an MCP host such as Claude Desktop and consents in the browser. The MCP client then acts with that user's permissions, using short-lived tokens that the user, a project administrator, or an organization owner can revoke at any time. During technical preview, OAuth for the MCP server is available on Serverless projects only. To register a client, you provide a single Serverless project, so each client is scoped to one project. ## OAuth or API keys? Both methods let an MCP client reach the Elastic Agent Builder MCP server. Choose based on how the client runs and who acts through it. | | OAuth | API key | |----------|--------------------------------------------------------------------------|--------------------------------------------------| | Best for | Interactive agents acting on behalf of a person (Claude Desktop, Cursor) | Automation and static, machine-to-machine access | | Identity | The consenting user; permissions are the user's live permissions | The key's snapshotted permissions | | Credential lifetime | Short-lived tokens, refreshed automatically | Long-lived until it expires or is revoked | | Setup | Register an MCP client, then consent in the browser | Generate a key and add it to the client configuration | For API key configuration, refer to [Elastic Agent Builder MCP server](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-server). The rest of this page covers the OAuth path. ## Key concepts Understanding these terms makes the setup and management pages easier to follow. - **MCP host**: The application a user runs that contains MCP clients, such as Claude Desktop or Cursor. Users connect hosts; hosts use clients. - **MCP client**: The registered application that holds the credentials (a client ID, and a client secret for confidential clients). You create one in Kibana before connecting a host. - **MCP server**: The interface that exposes Elastic Agent Builder tools to MCP hosts. The MCP server is the only resource the OAuth tokens grant access to. This is separate from [MCP tools](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/tools/mcp-tools), which let your agents call external MCP servers — the reverse direction. - **App connection**: The record created when a user consents, linking that user, the MCP client, and the Serverless project. A connection is the unit of access and revocation. If two people use the same client ID, each consent creates a separate connection. ## How it works 1. A user [creates an MCP client](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-client-create) in Kibana, scoped to one Serverless project, and copies the generated configuration into their MCP host. 2. The first time the host needs access, it opens a browser for the user to authenticate and consent. Authentication is always required for consent, even if the user already has an active Elastic Cloud session. 3. On consent, an app connection is created and the client receives tokens. The MCP client presents these to the MCP server, which exchanges them internally to access Elasticsearch with the user's current permissions. 4. The user, a project administrator, or an organization owner can [revoke](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-client-revoke) the connection or the whole client at any time. OAuth tokens are accepted only by the Elastic Agent Builder MCP server. They don't grant direct access to Kibana or Elasticsearch APIs. ### About tokens Access tokens are short-lived and refreshed automatically in the background, so an active connection keeps working without user action. Refresh is inactivity-based: after 30 days without use, a connection expires and the user must consent again. Because expiry is detected only when a connection is next used, a connection that shows as connected might be idle and not yet revalidated. ### Permissions A connected client inherits the consenting user's permissions in the project. When a user's permissions change, the change applies on the next token refresh; changes to a custom role apply immediately. ## Next steps - [Create an MCP client](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-client-create) - [Connect an MCP host to an MCP client](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-client-connect) ## Related pages - [Revoke an MCP client or connection](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-client-revoke) - [Manage application connections](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/deploy-manage/users-roles/cloud-organization/manage-mcp-client-connections) at the organization level - [Elastic Agent Builder MCP server](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-server)