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. There are two ways in: a scoped environment client key, or signing in with your Enterspeed account. For step-by-step wiring guides, 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 authenticate in one of two ways:

A scoped environment client key, sent in an x-api-key header. The key names its own tenant and environment, and carries any index restrictions you set on it. This is the tighter boundary, and it is described below.
Signing in with your Enterspeed account, over OAuth. This is the route for clients that take a server URL and nothing else, such as claude.ai and Claude Desktop’s Connectors screen. See Signing in instead of using a key.

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 a missing or 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 under-scoped.

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.

Required scopes

The platform supports component-scoped environment keys. For MCP use, your key must include:

Scope	Why	Grants
`MCP Server (AI Agent Access)`	Gates the MCP tool endpoints. Without it, the server sees zero dynamic or per-index tools.	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 `enterspeed_query` tool) and auto-indexed data* (the 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

Sign in to the Enterspeed Management App.
Select the tenant and environment you want the AI client to query.
Go to Environment → API Keys.
Click Create API key.
Pick the AI Assistant preset.
(Optional) Set an Index Scope pattern like blog* to restrict access.
Give the key a descriptive name, e.g. claude-prod-blog-assistant.
Click Create — the key is shown once. Store it in your secret manager immediately.

The new key has the form environment-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. 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 three layers. A signed-in session also gets three tools for choosing its tenant and environment — see Signing in instead of using a key. 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. Unified — an enterspeed_query tool that targets several indexes in a single call. All three 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 per-index layer is missing — which 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 enterspeed_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 discovers types via get_indices_raw_source_entities_by_source_group_alias, then pulls five entities via get_source_items. 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	`x-api-key` missing or malformed, or on the sign-in route, the sign-in has expired	Confirm the header is present on every MCP request, or reconnect and sign in again.
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.
`401` on every request	Wrong key type — a Management API key instead of 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.

Signing in instead of using a key

Some clients take a server URL and nothing else — claude.ai in the browser and Claude Desktop’s Connectors screen are the common examples. They have no field for a custom HTTP header, so they cannot send x-api-key. Those clients sign you in instead. Add https://mcp.query.enterspeed.com/ as a custom connector, authenticate with your Enterspeed credentials in the browser window that opens, and the session acts as you rather than as a key. The two routes 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 — 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 key-authenticated session is not offered them, because the key already answers both questions.

What to expect the first time you use the sign-in route:

An environment client appears in your tenant. The first time a context is selected in an environment, the server creates an environment client there named Enterspeed MCP (sign-in), with the Query API and MCP Server scopes and no index scope, and uses it for the session. Later sessions, including other people’s, reuse it — there is one per environment, not one per person. You will see it in the environment’s client list in the Management App. Deleting it revokes the access; the next selection creates it 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.

Next steps

Connecting a client — VS Code, Claude Code, Claude Desktop, or the Anthropic Messages API in C#.
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

Signing in instead of using a key

Next steps

​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

​Signing in instead of using a key

​Next steps

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

Signing in instead of using a key

Next steps