Connecting a client

The Enterspeed Query MCP Server speaks plain MCP Streamable HTTP, so any MCP-capable client can use it. This page covers the four most common integrations; every other client follows one of the same two patterns — see Other MCP clients at the bottom. You need the production endpoint in every case:

https://mcp.query.enterspeed.com/

How you authenticate is a choice between two routes, and it decides what else you need:

A scoped environment client key (Query API + MCP Server at minimum), sent as an x-api-key header. The key names its own tenant and environment, and carries whatever index scope you gave it. See Creating a scoped key.
Signing in with your Enterspeed account, over OAuth. Nothing to issue and nothing to store, but the session has to be told which tenant and environment to work in before any query tool runs.

Not every client can do both. A client that lets you set a custom HTTP header can use either; one that only takes a URL — such as Claude Desktop’s Connectors screen — can only sign you in.

Configure the root URL with the http transport type. There is no separate /sse endpoint — the server delivers its responses as a server-sent event stream on the root URL itself.

Pick your client

VS Code (GitHub Copilot)
Claude Code CLI
Claude Desktop
Anthropic Messages API (C#)

VS Code’s GitHub Copilot reads MCP servers from an mcp.json file. For a single workspace, put the config at .vscode/mcp.json; for every workspace, use the MCP: Open User Configuration command from the command palette.

{
  "servers": {
    "enterspeedQuery": {
      "type": "http",
      "url": "https://mcp.query.enterspeed.com/",
      "headers": {
        "x-api-key": "environment-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

Reload the window (Developer: Reload Window from the command palette) and open the Copilot chat pane. The Enterspeed tools appear in the tool picker once Copilot connects.

Never commit .vscode/mcp.json with a real key. Use ${input:enterspeed-key} with a matching inputs entry so VS Code prompts for the key on first use, or put the config in your user profile instead of the workspace.

claude mcp add enterspeed --scope user --transport http "https://mcp.query.enterspeed.com/" \
  -H "x-api-key: environment-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

To sign in instead of using a key, leave out the -H line. Then start a session, run /mcp, pick enterspeed, and sign in with your Enterspeed credentials in the browser window that opens.

The user scope (--scope user) installs the server for the current user across all projects. Use --scope project to install it for the current project only but for all users — that writes a checked-in .mcp.json, so use an environment variable for the key rather than pasting it.

Then start a session and ask Claude to list your indices:

claude
> List the Enterspeed indices I have access to.

The CLI stores the server configuration under ~/.claude.json. Edit that file if you need to tweak the header or URL afterwards.

Claude Desktop reaches the Enterspeed Query MCP Server in one of two ways. Which one you want depends on how you intend to authenticate.

Route	Authenticates as	Use it when
Connectors	Your Enterspeed user account, over OAuth	You want to connect in under a minute, with no config file and no key to handle.
Config file + `mcp-remote`	A scoped environment client key	You want the connection pinned to one environment and one index scope.

Route 1 — Connectors

Claude Desktop’s Connectors screen takes a remote MCP URL directly. There is no config file to edit and no key to paste.

Open Settings → Connectors.
Click Add custom connector.
Give it a name — for example Enterspeed Query — and enter the server URL:

https://mcp.query.enterspeed.com/

Click Add. A browser window opens. Sign in with your Enterspeed credentials.
Back in Claude, pick the tenant and environment this session should work in — see the note below.

The Connectors screen cannot send an x-api-key header. It accepts a URL and authenticates by signing you in; there is no field for a custom header. If you have a scoped environment client key, this is not where it goes — use Route 2 instead.

A signed-in session starts without a tenant or environment, and no query tool works until you choose one. Signing in tells the server who you are, not which environment you mean, so get_indices and the query_* tools have nothing to run against until the session is pointed somewhere.A signed-in session is given three extra tools for this — list_available_contexts, select_context, and current_context. You do not have to call them by hand; just ask:

List my available Enterspeed contexts, then select the production environment.

If you belong to exactly one tenant with exactly one environment, asking Claude to select your context is enough — it resolves to the only one available.The first selection in an environment sets up an environment client for the sign-in route, and the first query needs a short wait after it. A selection can also need repeating after a reconnect. See what to expect from the sign-in route.

Route 2 — Config file with a scoped key

claude_desktop_config.json starts local programs and talks to them over stdio. It has no remote transport, so a URL and a headers block in that file do not reach a remote server — you bridge to one instead.mcp-remote is that bridge: Claude Desktop launches it locally over stdio, and it opens the Streamable HTTP connection to Enterspeed with your header attached. This is the route that carries a scoped environment client key.Open your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

You can also reach it from Settings → Developer → Edit Config.Add the mcpServers entry:

{
  "mcpServers": {
    "enterspeedQuery": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.query.enterspeed.com/",
        "--header",
        "x-api-key:environment-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      ]
    }
  }
}

If the file already has an mcpServers object, add the entry to it rather than replacing the file.Fully quit and relaunch Claude Desktop. The Enterspeed tools now appear in the tool picker.

Two things to watch in that block:

Node.js must be installed — the bridge runs through npx.
Write the header with no space after the colon (x-api-key:environment-…). The value is passed through as one argument, and a space splits it.

If Claude Desktop connects but shows “no tools discovered”, the key is almost certainly missing the MCP Server scope. Create a new key using the AI Assistant preset.

This is the production path: a C# service opens an MCP session to the Enterspeed server, discovers the available tools, and runs a tool-use loop with Claude. The x-api-key header is set once on the MCP transport.

Why not the inline mcp_servers feature? Anthropic’s inline remote-MCP connector forwards an Authorization: Bearer <token> header to the upstream MCP server and does not let you override the header name. The Enterspeed MCP server reads x-api-key. Driving the tool-use loop yourself (as below) works today and gives you full control over retries, logging, and cost.

Project setup

The loop uses two NuGet packages: Anthropic.SDK for the Messages API and ModelContextProtocol for the MCP session.

dotnet new console -n EnterspeedClaudeClient
cd EnterspeedClaudeClient
dotnet add package Anthropic.SDK
dotnet add package ModelContextProtocol
dotnet user-secrets init
dotnet user-secrets set "ANTHROPIC_API_KEY"   "sk-ant-..."
dotnet user-secrets set "ENTERSPEED_MCP_KEY"  "environment-xxxxxxxx-..."

Program.cs

using Anthropic.SDK;
using Anthropic.SDK.Messaging;
using Microsoft.Extensions.Configuration;
using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol.Transport;
using System.Text.Json;

var config = new ConfigurationBuilder()
    .AddUserSecrets<Program>()
    .AddEnvironmentVariables()
    .Build();

var anthropicKey  = config["ANTHROPIC_API_KEY"]!;
var enterspeedKey = config["ENTERSPEED_MCP_KEY"]!;

// 1. Open an MCP session against the Enterspeed server
var transport = new SseClientTransport(new SseClientTransportOptions
{
    Endpoint = new Uri("https://mcp.query.enterspeed.com/"),
    AdditionalHeaders = new Dictionary<string, string>
    {
        ["x-api-key"] = enterspeedKey
    }
});

await using var mcp = await McpClientFactory.CreateAsync(transport);

// 2. Discover the tools this key is allowed to use
var mcpTools = await mcp.ListToolsAsync();

// 3. Hand the tool schemas to Claude as Messages API tools
var claude = new AnthropicClient(new APIAuthentication(anthropicKey));

var tools = mcpTools
    .Select(t => new Tool
    {
        Name        = t.Name,
        Description = t.Description ?? string.Empty,
        InputSchema = t.InputSchema
    })
    .ToList();

var messages = new List<Message>
{
    new(RoleType.User,
        "Find the three most recent published blog posts and summarise " +
        "them in one sentence each.")
};

// 4. Tool-use loop — repeat until Claude produces a final answer
while (true)
{
    var response = await claude.Messages.GetClaudeMessageAsync(new MessageParameters
    {
        Model     = AnthropicModels.Claude4Sonnet,
        MaxTokens = 4096,
        Messages  = messages,
        Tools     = tools
    });

    // Record Claude's turn
    messages.Add(new Message(response));

    if (response.StopReason != "tool_use")
    {
        Console.WriteLine(response.Message);
        break;
    }

    // Execute every tool_use block via the MCP client and feed results back
    foreach (var block in response.Content.OfType<ToolUseContent>())
    {
        var args = block.Input.Deserialize<Dictionary<string, object?>>()
                   ?? new();
        var mcpResult = await mcp.CallToolAsync(block.Name, args);

        messages.Add(new Message
        {
            Role    = RoleType.User,
            Content = new List<ContentBase>
            {
                new ToolResultContent
                {
                    ToolUseId = block.Id,
                    Content   = mcpResult.Content.FirstOrDefault()?.Text ?? string.Empty
                }
            }
        });
    }
}

Run it:

dotnet run

Expected output includes a short summary of three blog posts, and the loop’s intermediate turns show Claude calling query_blog (or the equivalent per-index tool for whatever index the key is scoped to).

SDK property names. The exact property names on ToolUseContent, ToolResultContent, and the Message / Tool shapes evolve with the Anthropic.SDK package. If a symbol above does not resolve, check the current release notes for the corresponding type name — the orchestration pattern (list tools once, loop until StopReason != "tool_use") stays the same.

Keeping costs under control

Cache the tool list. Call ListToolsAsync() once per session, not per request. The MCP server also caches per API key for 5 minutes, so repeat calls are cheap even if you do list more often.
Narrow the tool set with an Index Scope. Fewer indices means fewer query_* tools surfaced to Claude, which means fewer input tokens.
Use prompt caching on the tool list. When you pass tools to the Messages API, mark the list with cache_control: { type: "ephemeral" } via CacheControl-style helpers in Anthropic.SDK — see the package README for the current property name.

Other MCP clients

The four clients above are the ones we test against regularly, but the MCP server is client-agnostic. Any MCP-capable client follows one of the two routes — point it at https://mcp.query.enterspeed.com/ with http transport, and either set an x-api-key header or let the client sign you in with your Enterspeed account. Some known-good examples, all of which can set a header:

Cursor — .cursor/mcp.json, under mcpServers, with url and headers (Cursor uses mcpServers where VS Code uses servers).
Windsurf — settings → Cascade → MCP Servers, using the URL + header form.
Continue — ~/.continue/config.json under experimental.modelContextProtocolServers.
Zed — settings under "context_servers".

If your client does not support custom headers, you have two options. Add the server as a custom connector and sign in with your Enterspeed account, the way Claude Desktop’s Connectors route works — this is the better one, and it is what claude.ai in the browser uses. Failing that, pass the key as an ?apiKey= query-string parameter on the MCP URL. Avoid the query string in production: the key ends up in request logs along the whole path.

Signing in works on claude.ai in the browser too. Open Settings → Connectors, choose Add custom connector, and give it https://mcp.query.enterspeed.com/. As with Claude Desktop, a browser connector cannot send an x-api-key header — it signs you in instead, and the session needs a tenant and environment selected before any query tool runs.

Troubleshooting

Symptom	Likely cause	Fix
Client responds “I don’t have any tools”	MCP server entry missing, or the URL is wrong	Confirm the config was reloaded by the client; hit `/health` on the MCP endpoint.
Every tool call returns “forbidden”	`x-api-key` forwarded correctly but scope missing	Add `Query API` to the environment client.
`mcp add` / config reload fails with “failed to establish connection”	Local proxy, VPN, or corporate firewall stripping SSE headers	Bypass the proxy (`NO_PROXY=mcp.query.enterspeed.com`) or try a different network.
Tools list is empty after reload	Client caches tool lists per session	Fully quit and relaunch the client (on macOS, Cmd-Q in Claude Desktop; Developer: Reload Window in VS Code).
`401` on every request	Wrong key type — Management API token instead of environment-client key	Create an environment client key, not a Management API token.
Connected and signed in, but every index or query tool fails	The session has not been pointed at a tenant and environment yet	Ask the client to list your available Enterspeed contexts and select one. This applies to the sign-in route only — a key already names its environment.
Claude Desktop shows the server but no tools, and the config uses `url` and `headers`	`claude_desktop_config.json` has no remote transport, so those fields go nowhere	Use the `mcp-remote` bridge shown above, or add the server under Settings → Connectors instead.

Next steps

Overview — sample prompts and scope reference.
Connecting an agent — Azure AI Foundry and custom-agent wiring.

Overview

Schema reference

API

Integrations

Tutorials

Best practices

CLI

MCP server

Pick your client

Route 1 — Connectors

Route 2 — Config file with a scoped key

Project setup

Program.cs

Keeping costs under control

Other MCP clients

Troubleshooting

Next steps

​Pick your client

​Route 1 — Connectors

​Route 2 — Config file with a scoped key

​Project setup

​Program.cs

​Keeping costs under control

​Other MCP clients

​Troubleshooting

​Next steps

Pick your client

Route 1 — Connectors

Route 2 — Config file with a scoped key

Project setup

Program.cs

Keeping costs under control

Other MCP clients

Troubleshooting

Next steps