> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enterspeed.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Connect an AI client to the Enterspeed Query API — query your indexes, views, and auto-indexed source entities in natural language.

The Enterspeed Query MCP Server turns the Enterspeed Query API into a set of [Model Context Protocol](https://modelcontextprotocol.io/) tools that AI clients (Claude, Cursor, custom agents, Azure AI Foundry, etc.) can discover and call. You do not need to host anything yourself — Enterspeed runs the server for you.

This page tells you **where the server lives**, **how authentication works**, and **what scopes to request**. You connect by [signing in with your Enterspeed account](#what-to-expect-when-you-sign-in). A scoped environment client key is the alternative, for an agent that runs unattended or a connection fixed to one environment and one index scope. For the steps for each client, see [Connecting a client](/enterspeed/mcp-server/query-mcp/connecting-a-client) and [Connecting an agent](/enterspeed/mcp-server/query-mcp/connecting-an-agent).

To configure your tenant rather than query it, see [Management MCP](/enterspeed/mcp-server/management-mcp/overview).

## Hostname

| Environment | URL | Transport |
| - | - | - |
| **Production** | `https://mcp.query.enterspeed.com/` | MCP Streamable HTTP |

A health check is available without authentication:

```bash theme={null}
curl -s "https://mcp.query.enterspeed.com/health"
# "ok"
```

<Info>
  The server speaks **MCP Streamable HTTP** on the root URL, and nothing else. Choose the **HTTP** or **Streamable HTTP** transport in your client. The older SSE transport does not work: a client set to *SSE* fails on its first request with an HTTP 400 error. There is no `/sse` endpoint — always configure the root URL.
</Info>

## How authentication works

The MCP server is a thin proxy. All authorisation decisions happen in the Enterspeed Query API.

You connect by **signing in with your Enterspeed account**, over OAuth. You give your client the server URL and sign in in a browser window. Then you ask the session to select the tenant and environment it works in. See [What to expect when you sign in](#what-to-expect-when-you-sign-in).

The server also accepts **a scoped environment client key**, sent in an `x-api-key` header. Use one for an agent that runs unattended, because it cannot complete a browser sign in. Use one too when you want the connection fixed to one environment and one index scope. The key names its own tenant and environment, and carries any index restrictions you set on it.

```
Key:      AI client ──x-api-key──► mcp.query.enterspeed.com ──x-api-key──► query.enterspeed.com
Sign in:  AI client ──sign in────► mcp.query.enterspeed.com ──key of the ──► query.enterspeed.com
                                                               selected environment
                                                                           │
                                                           validates scopes + IndexScope
```

With a key, the MCP server forwards it as-is, and the Query API validates the scope and any index restrictions before returning data. Clients send it as a single HTTP header on every MCP request:

```
x-api-key: environment-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

The key is a **scoped environment client key** issued from the Enterspeed Management App. It is *not* a Management API key. [Management MCP](/enterspeed/mcp-server/management-mcp/overview) does not take a key at all — you sign in to it with your Enterspeed account.

<Info>
  The server also accepts an `?apiKey=` query-string fallback for tools that cannot set headers. Prefer the header whenever possible: a key in a URL ends up in access logs along the whole request path.
</Info>

The key is checked when a tool is *called*, not when the session is opened. A client with an invalid key can still connect and list the static tools, which is why an unexpectedly short tool list is the fastest signal that a key is wrong or has too few scopes. A request that carries no key and has not signed in is refused with a `401`, and the response points the client to the sign in.

### Rate limit

Requests are counted per API key — or, on a signed-in session, per signed-in person — over a fixed one-minute window, with a limit of **120 requests per minute**. Exceeding it returns:

```
HTTP 429 Too Many Requests
Retry-After: <seconds>

Too many requests. Retry after <n> seconds.
```

Well-behaved MCP clients back off and retry. The `/health` endpoint is exempt. The limit is counted by each server instance separately, so treat it as the rate a client should stay under rather than an exact figure.

## What to expect when you sign in

Give your client `https://mcp.query.enterspeed.com/`, and it opens a browser window where you sign in with your Enterspeed credentials. [Connecting a client](/enterspeed/mcp-server/query-mcp/connecting-a-client) has the steps for each client.

Signing in and a scoped key differ in what they answer.

| | Scoped key | Signing in |
| - | - | - |
| Names the tenant and environment | The key does, on its own | You do, in each session |
| Index scope | Whatever you set on the key | Not applied. Access follows the environment you select. |
| Where it lives | A secret you store and rotate | An environment client Enterspeed creates in your tenant with your permission. See below. |

<Note>
  **A signed in session has no tenant or environment until it is given one, and no index or query tool works before that.** Such a session is offered three extra tools, `list_available_contexts`, `select_context` and `current_context`, so asking the client to list your contexts and select one is enough. A session that uses a key is not offered them, because the key already answers both questions.
</Note>

When you first sign in and select an environment, expect the following.

* **You are asked before an environment client is created in your tenant.** The first time a context is selected in an environment, the server needs an environment client there named **Enterspeed MCP (sign-in)**, with the `Query API` and `MCP Server` scopes and no index scope. It creates nothing on that first call. Your AI client tells you what will be created and asks for your permission, and the environment client is only created once you agree. It is created with your own account, as if you had added it in the Management App. If you decline, nothing is created, and you can connect with a [scoped key](#creating-a-scoped-key) of your own instead.
* **It is reused after that.** Later sessions, including other people's, reuse the same environment client without asking. There is one per environment, shared by everyone who signs in. You will see it in the environment's list of environment clients in the Management App. Deleting it revokes the access, and the next selection asks again.
* **The first query needs a short wait.** A newly created client takes about ten seconds to become usable, and a query made sooner fails. The select response says so when it has just created the client. Wait, then query.
* **The selection can need repeating.** It is held in memory by the server instance that handled it. If your client reconnects, or a later request is served by a different instance, a tool call can come back saying no context is selected. Nothing is lost. Select the context again and carry on.

## Required scopes

This section and the next two apply when you connect with a key. The platform lets you limit an environment key to the APIs it needs. For MCP use, your key **must** include both scopes in this table.

| Scope | Why | Grants |
| - | - | - |
| `MCP Server` | Gates the MCP tool endpoints. Without it, the server sees none of the dynamic tools or the tools for each index. | Ability to list MCP tools. |
| `Query API` | Needed to query your Enterspeed data. | Access to both **schema-transformed data** (the `query_*` tools and the unified `query` tool) and **auto-indexed data** (the `query_source_*` tools and the other source tools). |

`MCP Server` alone is not useful — it must be combined with `Query API`, and Enterspeed enforces that pairing when you save the client.

<Info>
  There are exactly four scopes: **Delivery API**, **Query API**, **Routes API**, and **MCP Server**. There is no separate Source API scope — access to auto-indexed source entities comes with **Query API**, narrowed by the [index scope](#index-scopes) below.
</Info>

### Scope presets

When creating an environment client, the Management App exposes these presets so you do not have to toggle scopes manually:

| Preset | Scopes bundled | Typical use case |
| - | - | - |
| **Standard** | Delivery + Query + Routes | Traditional delivery clients, no AI. |
| **AI Assistant** | Query + MCP Server | Full data access for AI agents — both schema-transformed data and auto-indexed data. |

The **AI Assistant** preset is the right default for MCP integrations.

See [Using environment clients](/enterspeed/getting-started/environment-clients#scope-presets) for the full table and how to manage scopes in the Management App.

## Index scopes

On top of component scopes, each environment client can carry an optional **Index Scope** that restricts *which indices* the key can see. Patterns are matched against the fully-qualified index name.

| Pattern | Matches |
| - | - |
| `blog*` | every index whose name starts with `blog` |
| `cms:*` | every index under the `cms` source group |
| `*:entity` | every index ending in `entity` |
| *(unset)* | no restriction — all indices the scope allows |

Filtering is enforced by the Query API, so AI clients get a pre-trimmed tool list. This is ideal when you want to give a public-facing AI assistant access to, say, only a marketing-blog index, without exposing the rest of the environment.

<Warning>
  **An empty index scope means unrestricted, not restricted.** Leaving it unset grants every index the key's scopes allow. If you want to limit an AI assistant to a subset of your data, you must set a pattern explicitly — omitting the field is the *open* setting, not the safe one.
</Warning>

Patterns are read in two families, split by the colon:

* **Without a colon** — matches index names, for example `blog*`.
* **With a colon** — matches auto-indexed source entities as `sourceGroup:entityType`, for example `cms:*`.

Each family is only restricted if you supply at least one pattern for it. So a key configured with only `cms:*` restricts auto-indexed source entities while leaving index queries **unrestricted**. Set patterns in both families when you want to narrow both.

## Creating a scoped key

A scoped key is the API key of an environment client.

1. Sign in to the **Enterspeed Management App** and select your tenant.
2. Go to **Settings → Environments**.
3. Under **Environment clients**, click **Create**.
4. Give the environment client a descriptive name, for example `claude-prod-blog-assistant`, and select the environment you want the AI client to query.
5. Under **Quick Setup**, pick the **AI Assistant** preset. It selects **Query API** and **MCP Server**.
6. *(Optional)* To restrict access, choose **Select specific indices** and add a pattern like `blog*` under **Or use wildcard patterns**.
7. Click **Create**. The app then asks which domains the client may be used from. The client has already been created at that point, so you can choose **Cancel** there if you do not want to add a domain.

The key appears in the **API Key** column of the environment client list. It has the form `environment-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. Store it in your secret manager rather than in a file you commit.

To use an environment client you already have, open its menu in the list and choose **Edit Scopes** instead.

<Warning>
  **Choosing a preset replaces the environment client's scopes.** The **AI Assistant** preset sets exactly **Query API** and **MCP Server**, so an existing client that also had **Delivery API** or **Routes API** loses them, and its key stops working against those APIs. To keep them, leave the preset alone and tick **MCP Server** alongside the scopes the client already has. It needs **Query API** to be ticked too.
</Warning>

See [Using environment clients](/enterspeed/getting-started/environment-clients) for the full environment-client flow, including regenerating a key.

## What tools the agent gets

Every tool is a read — the server has no way to change your data or your configuration. To configure a tenant, an agent needs [Management MCP](/enterspeed/mcp-server/management-mcp/overview) instead.

The tool list is assembled per key, so two clients pointed at the same server can see different tools. It comes in four layers. A signed in session also gets three tools for choosing its tenant and environment. See [What to expect when you sign in](#what-to-expect-when-you-sign-in).

**Always present** — the same eight tools for everyone:

| Tool | What it does |
| - | - |
| `get_indices` | Lists the indexes the key can see. The usual starting point. |
| `describe_index` | Describes one index — its fields, and which are searchable or sortable. |
| `get_query_items` | Queries a single index with filters, sorting, pagination, and facets. |
| `get_multiple_query_items` | Queries several indexes in one round-trip. |
| `get_source_items` | Fetches auto-indexed source entities. |
| `get_indices_raw_source_entities_by_source_group_alias` | Discovers which entity types exist in a source group. |
| `get_operators` | Lists the filter operators available to you. |
| `retrieve_query_api_status` | Reports Query API status. |

**Per index** — one `query_<indexName>` tool for each index the key can reach, generated from that index's own fields. These give an agent a typed, index-specific way to query, so it does not have to construct a generic filter by hand.

**Per source** — one `query_source_<sourceGroup>_<entityType>` tool for each auto-indexed source group and entity type the key can reach, for example `query_source_cms_article`, generated from that entity type's own fields. The group and type appear in lower case.

**Unified** — a `query` tool that targets several indexes in a single call.

All four layers respect the key's [index scope](#index-scopes), so the agent is handed a pre-trimmed list rather than being told "no" after it tries.

<Tip>
  If an agent only ever shows the eight tools above, the layer of tools for each index is missing. On a signed in session, select a context first. The server does not tell your client when the list changes, so the tools for each index appear only if the client asks for the list again in the same session. `get_indices` and `get_query_items` still reach every index in the selected environment. With a key, it almost always means the key lacks the `MCP Server` scope, or is invalid.
</Tip>

## Sample prompts

Use these when demoing or smoke-testing a fresh MCP connection.

### Connectivity check

> List the Enterspeed indices you have access to, then tell me how many of them there are and what their naming convention looks like.

Expected behaviour: the agent calls the index-listing tool and returns a list filtered by the key's Index Scope.

### Schema discovery

> Describe the `blog` index. What fields does it have, which ones are searchable, and which are sortable?

Expected behaviour: the agent calls `describe_index` with `indexAlias: blog`. A good answer groups fields by type (keyword, text, date, integer, etc.).

### Single-index query

> Find the five most recent blog posts authored by `alice` and return their titles, publish dates, and URLs.

Expected behaviour: the agent calls `query_blog` with a filter on `author = alice`, sort descending by `publishedAt`, and `pagination.pageSize = 5`.

### Multi-index query

> Across the `products` and `productsv2` indices, find items with `category = beverages` and under 100 kcal per 100g. Return the top three sorted by energy ascending.

Expected behaviour: the agent calls the unified `query` tool with a `queries` array that targets both indices in a single round-trip.

### Auto-indexed data exploration

> Show me five raw source entities of type `article` from the `cms` source group. Which fields are set on the first one?

Expected behaviour: the agent calls `query_source_cms_article` with `pagination.pageSize = 5`. Access to auto-indexed data comes with the `Query API` scope — no extra scope is needed beyond the standard `Query API` + `MCP Server` combination.

### Authorisation check

> Which operators can I use to filter queries in Enterspeed?

Expected behaviour: the agent calls the `get_operators` tool. The list typically includes `contains`, `equals`, `notEquals`, `in`, `lessThan`, `lessThanOrEquals`, `greaterThan`, and `greaterThanOrEquals` — the concrete set is data-driven, so trust the tool response over this page.

### Tool-listing sanity check

> What tools do you have available and which Enterspeed indices are they tied to?

Expected behaviour: the agent enumerates the full tool set. If the dynamic and per-index groups are empty, the key is most likely missing the `MCP Server` scope — that is the fastest way to spot a misconfigured key.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| `401 Unauthorized` from the MCP server | The client is not signed in, its sign in has expired, or it sends no key | Reconnect and complete the sign in. If you use a key, confirm the `x-api-key` header is present on every MCP request. |
| Agent lists only a small static set of tools | Key is missing the `MCP Server` scope | Recreate the key with the *AI Assistant* preset. |
| Agent sees fewer indices than expected | `IndexScope` pattern is too narrow | Widen the Index Scope on the environment client, or remove it for all-index access. |
| Tools listed but `query_*` returns "forbidden" | Key has `MCP Server` but not `Query API` | Add the `Query API` scope. |
| Connected with a key, but every index and query tool fails | The key is a Management API key, not an environment client key | Create an **environment client** key. A Management API key does not work here, and [Management MCP](/enterspeed/mcp-server/management-mcp/overview) does not take keys at all. |
| `429` with a `Retry-After` header | More than 120 requests in a minute on this key, or from your signed-in sessions | Let the client back off and retry. |
| Client cannot connect at all | Configured with a `/sse` path, or a proxy that buffers streamed responses | Use the root URL. Streamed responses must pass through unbuffered. |

## Next steps

* [Connecting a client](/enterspeed/mcp-server/query-mcp/connecting-a-client) to sign in from Claude Code, Codex, Gemini CLI, Copilot CLI, Claude.ai, ChatGPT, Claude Desktop, Cursor or VS Code, or to connect with a scoped key.
* [Connecting an agent](/enterspeed/mcp-server/query-mcp/connecting-an-agent) — wire a custom C# agent or Azure AI Foundry to the MCP server.
* [Management MCP](/enterspeed/mcp-server/management-mcp/overview) — configure your tenant instead of querying it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.