Overview

The Enterspeed Query MCP Server turns the Enterspeed Query API into a set of Model Context Protocol 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. 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 and Connecting an agent. To configure your tenant rather than query it, see Management MCP.

Hostname

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

A health check is available without authentication:

curl -s "https://mcp.query.enterspeed.com/health"
# "ok"

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.

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. 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 does not take a key at all — you sign in to it with your Enterspeed account.

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.

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

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.

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

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

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

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.

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.

Sign in to the Enterspeed Management App and select your tenant.
Go to Settings → Environments.
Under Environment clients, click Create.
Give the environment client a descriptive name, for example claude-prod-blog-assistant, and select the environment you want the AI client to query.
Under Quick Setup, pick the AI Assistant preset. It selects Query API and MCP Server.
(Optional) To restrict access, choose Select specific indices and add a pattern like blog* under Or use wildcard patterns.
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.

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.

See Using 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 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. 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, so the agent is handed a pre-trimmed list rather than being told “no” after it tries.

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.

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 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 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 — wire a custom C# agent or Azure AI Foundry to the MCP server.
Management MCP — configure your tenant instead of querying it.

Schema reference

API

Integrations

Tutorials

Best practices

CLI

MCP server

Overview

Hostname

How authentication works

Rate limit

Required scopes

Scope presets

Index scopes

Creating a scoped key

What tools the agent gets

Sample prompts

Connectivity check

Schema discovery

Single-index query

Multi-index query

Auto-indexed data exploration

Authorisation check

Tool-listing sanity check

Troubleshooting

Next steps

​Hostname

​How authentication works

​Rate limit

​What to expect when you sign in

​Required scopes

​Scope presets

​Index scopes

​Creating a scoped key

​What tools the agent gets

​Sample prompts

​Connectivity check

​Schema discovery

​Single-index query

​Multi-index query

​Auto-indexed data exploration

​Authorisation check

​Tool-listing sanity check

​Troubleshooting

​Next steps

Hostname

How authentication works

Rate limit

What to expect when you sign in

Required scopes

Scope presets

Index scopes

Creating a scoped key

What tools the agent gets

Sample prompts

Connectivity check

Schema discovery

Single-index query

Multi-index query

Auto-indexed data exploration

Authorisation check

Tool-listing sanity check

Troubleshooting

Next steps