OAuth for MCP clients
The Elastic Agent Builder MCP server supports OAuth 2.1 as a way for MCP clients to authenticate on behalf of a user, alongside API keys.
OAuth is best for interactive, agentic use cases: instead of configuring a static, long-lived API key, a user connects an MCP host such as Claude Desktop and authorizes the connection in the browser. The connection then acts with that user's own permissions, using short-lived tokens that the user, a project administrator, or an organization owner can revoke at any time.
OAuth for the MCP server is available on Serverless projects only. OAuth clients are registered within a specific Serverless project, so each client is scoped to one project.
The way that you configure your MCP server depends on your authentication method. Both methods let an MCP client reach the Elastic Agent Builder MCP server. To compare them, refer to MCP server authentication and configuration.
To learn how to configure your MCP server with API keys, refer to Authenticate MCP clients with API keys. The rest of this page describes configuring your MCP server with OAuth.
Understanding these terms makes the setup and management pages easier to follow.
| Term | Definition |
|---|---|
| MCP host | The application a user runs that contains MCP clients, such as Claude Desktop or Cursor. Users connect hosts; hosts use clients. |
| OAuth client | The OAuth client registration that holds the credentials (a client ID, and a client secret for confidential clients) your MCP host uses to authenticate to the MCP server. You create one in Kibana before connecting a host; the Kibana UI labels this an MCP client. |
| 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 the Model Context Protocol (MCP) tools in Elastic Agent Builder, which let your agents call external MCP servers. |
| App connection | The record created when a user authorizes a connection, linking that user, the OAuth client, and the Serverless project. A connection is established on top of an OAuth client, and is the unit of access and revocation. If two people use the same client ID, each authorization creates a separate connection. |
In practice, the pieces connect in order. An OAuth client is registered in Kibana, and its credentials are added to an MCP host such as Claude Desktop. The host's MCP client uses those credentials to reach the Elastic Agent Builder MCP server. When a user authorizes access, an app connection is created, and the host's tools then run with that user's permissions.
An OAuth flow follows these steps over its lifecycle:
- A user with Elastic Agent Builder access creates an OAuth client in Kibana, scoped to one Serverless project, and receive a client ID and an MCP server URL used to configure an MCP host.
- An end user adds the client ID and MCP server URL to their MCP host (AI agent). The first time the host needs access, it opens a browser for the user to authenticate and authorize access. Authentication is always required, but might not prompt for login if the user already has an active Elastic Cloud session.
- On authorization, an app connection is created and the host receives tokens. The OAuth client presents these to the MCP server, which exchanges them internally to access Elasticsearch with that user's current permissions.
- The user, a project administrator, or an organization owner can revoke a single connection or the entire client at any time, at the project or organization level.
OAuth tokens are accepted only by the Elastic Agent Builder MCP server. They don't grant direct access to Kibana or Elasticsearch APIs.
A single OAuth client registration can be reused by any number of people. After you create a client, you can share its connection details so that others configure the same client in their own MCP hosts (AI agents). Each person authenticates and authorizes access separately, which creates a distinct app connection scoped to that person's own permissions. Revoking one person's connection leaves the others active, while revoking the client ends access for everyone.
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 re-authorize. Because expiry is detected only when a connection is next used, a connection that shows as connected might be idle and not yet revalidated.
All application connections mirror the permissions of the user that authorizes the connection. If you authorize the connection and you have read and write permissions, then so will your connected application.
When a user's permissions change, the change applies on the next token refresh; changes to a custom role apply immediately.
You can use a secondary user with limited permissions to restrict what the connected application can access. Permissions follow the user who authorizes the connection, so ensure that user is signed in before authorizing it. This user does not need to be the same account used to create the OAuth client or manage application connections.
Use the following pages to create and manage OAuth access for MCP clients:
- Create an OAuth client in Elastic Agent Builder: Register a client in Elastic Agent Builder and get the client ID and MCP server URL your MCP host needs.
- Connect an MCP host to Elastic Agent Builder: Configure your MCP host with those values and complete browser authorization.
- Revoke an OAuth client or connection: Remove access for a single connection or an entire client at the project level.
- Manage application connections: Audit and revoke connections across your organization's Serverless projects in the Elastic Cloud Console.
- Elastic Agent Builder MCP server: Configure the Elastic Agent Builder MCP server and compare authentication methods.
- Elastic API keys: Authenticate to the MCP server with API keys instead of OAuth.