Skip to main content

Elasticsearch MCP server

Elasticsearch is a distributed, RESTful search and analytics engine that enables full-text search, complex queries, real-time analytics, and data aggregations at scale. With this MCP server, AI agents can search documents, create indexes, run analytics aggregations, and monitor cluster health through natural language commands.

Setting up an MCP server

This article covers the standard steps for creating an MCP server in AI Gateway and connecting it to an AI client. The steps are the same for every integration — application-specific details (API credentials, OAuth endpoints, and scopes) are covered in the individual application pages.

Before you begin​

You'll need:

  • Access to AI Gateway with permission to create MCP servers
  • API credentials for the application you're connecting (see the relevant application page for what to collect)

Create an MCP server​

Find the API in the catalog​

  1. Sign in to AI Gateway and select MCP Servers from the left navigation.
  2. Select New MCP Server.
  3. Search for the application you want to connect, then select it from the catalog.

Configure the server​

  1. Enter a Name for your server — something descriptive that identifies both the application and its purpose (for example, "Zendesk Support — Prod").
  2. Enter a Description so your team knows what the server is for.
  3. Set the Timeout value. 30 seconds works for most APIs; increase to 60 seconds for APIs that return large payloads.
  4. Toggle Production mode on if this server will be used in a live workflow.
  5. Select Next.

Configure authentication​

Enter the authentication details for the application. This varies by service — see the Authentication section of the relevant application page for the specific credentials, OAuth URLs, and scopes to use.

Configure security​

  1. Set any Rate limits appropriate for your use case and the API's own limits.
  2. Enable Logging if you want AI Gateway to record requests and responses for auditing.
  3. Select Next.

Deploy​

Review the summary, then select Deploy. AI Gateway provisions the server and provides a server URL you'll use when configuring your AI client.

Connect to an AI client​

Once your server is deployed, you'll need to add it to the AI client your team uses. Select your client for setup instructions:

Tips​

  • You can create multiple MCP servers for the same application — for example, a read-only server for reporting agents and a read-write server for automation workflows.
  • If you're unsure which OAuth scopes to request, start with the minimum read-only set and add write scopes only when needed. Most application pages include scope recommendations.
  • You can edit a server's name, description, timeout, and security settings after deployment without redeploying.

Authentication​

Elasticsearch supports multiple authentication methods. API keys are recommended for API access, and OAuth 2.0 via OIDC can be configured for enterprise SSO scenarios.

API Key Authentication:​

  • Header: Authorization: ApiKey {encoded_api_key}
  • Generate via: Kibana UI or REST API
  • Permissions: Configure role descriptors with specific cluster and index privileges

OAuth 2.0 (OIDC):​

  • Authorization URL: https://your-okta-domain.okta.com/oauth2/default/v1/authorize
  • Token URL: https://your-okta-domain.okta.com/oauth2/default/v1/token
  • Scopes: openid email profile
  • Requires: Elasticsearch OIDC realm configuration

Available tools​

The Elasticsearch MCP server exposes search, document management, index operations, and analytics aggregation APIs.

ToolPurpose
SearchFull-text search, fuzzy matching, filtered queries, multi-index search across documents
Document ManagementIndex, update, and delete documents; bulk operations; version control; retrieve by ID
Index ManagementCreate, delete, and reindex indices; manage mappings; configure aliases; set lifecycle policies
AggregationsMetrics (sum, average, min/max), bucket grouping, histogram, date histogram, pipeline aggregations
Cluster ManagementMonitor cluster health; view node status; manage shard allocation; configure cluster settings
Geospatial QueriesLocation-based searches; distance calculations; polygon searches; geographic aggregations

Tips​

Plan your mappings carefully before indexing data.

Choose appropriate field types for your query patterns and use nested documents for complex data structures.

Use filters for exact matches instead of queries when possible.

Implement pagination with search_after or scroll for large result sets.

Limit returned fields with source filtering.

Run aggregations on smaller datasets by applying filters first.

Use terms aggregations for categorical data.

Consider materialized views for frequently-run analytics.

Regularly check shard allocation and unassigned shards.

Configure appropriate numbers of replicas based on your availability needs.

Set up indices lifecycle management (ILM) for automatic rollover.

Generate separate API keys for different use cases with minimal necessary permissions.

Use role mappings to control access to indices and features.

Rotate credentials regularly.