Loading

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

Note

During technical preview, OAuth for the MCP server is available on Serverless projects only. 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.
MCP 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.
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 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.

The OAuth flow follows these steps:

  1. A user creates an MCP client in Kibana, scoped to one Serverless project, and receives a client ID and an MCP server URL. These values can be used to configure MCP hosts.
  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 the connection or the whole 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 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. Each person authenticates and consents 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 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.

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.

Use the following pages to create and manage OAuth access for MCP clients: