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. 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. Responses are delivered as a server-sent event stream on that same URL, so clients that label their transport SSE generally work when pointed at the root. There is no separate /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. Your MCP client sends a scoped environment client key on every request; the MCP server forwards it as-is; the Query API validates the scope and any index restrictions before returning data.

AI client ──x-api-key──► mcp.query.enterspeed.com ──x-api-key──► query.enterspeed.com
                                                                         │
                                                           validates scopes + IndexScope

Clients authenticate with 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 — that is what Management MCP uses.

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 over a rolling 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.

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. 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	Confirm the 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.
`401` on every request	Wrong key type — a Management API key instead of an environment client key	Create an environment client key. Management API keys belong to Management MCP.
`429` with a `Retry-After` header	More than 120 requests in a minute on this key	Let the client back off, or split work across keys.
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.

Known limitations

Custom connectors on claude.ai in the browser are not supported yet. Browser-based custom connectors cannot send a custom HTTP header, and this server requires x-api-key. Use Claude Code, Claude Desktop, VS Code, Cursor, or your own agent instead.We are working on OAuth support to remove this restriction. Until it ships, a header-capable client is required.

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

Known limitations

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

​Known limitations

​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

Known limitations

Next steps