Connecting a client

You connect a client to the Enterspeed Query MCP Server by signing in with your Enterspeed account. You give your client the server URL, it sends you to Enterspeed in a browser window, and you sign in with your normal Enterspeed credentials. Nothing goes into your client’s configuration except the URL.

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

The Management App gives you the same instructions. Go to Settings → Connect an agent, click Connect an agent and choose Query MCP. Once you are signed in, ask your client to select the tenant and environment you want to work in. Every signed in session needs this. See After you connect. If the connection is for an agent that runs unattended, or you want it fixed to one environment and one index scope, connect with a scoped key instead. See Using a scoped key instead.

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.

Connect by signing in

Every client below opens the remote server directly and takes you through the sign in itself. None of them needs Node.js or a bridge program on your machine. The mcp-remote bridge is only for a client that cannot open a remote server, and for Claude Desktop’s config file when you connect with a scoped key.

Agent CLIs

Claude Code
Codex
Gemini CLI
Copilot CLI

claude mcp add enterspeed-query --transport http "https://mcp.query.enterspeed.com/"

Start a session, run /mcp, and pick enterspeed-query to sign in. A browser window opens. Authenticate with your Enterspeed credentials.

This installs the server for the current project only. Add --scope user to make it available in every project.

codex mcp add enterspeed-query --url "https://mcp.query.enterspeed.com/"

Codex sees that the server asks for a sign in and opens a browser window for you straight away. To sign in again later, run codex mcp login enterspeed-query.

gemini mcp add --transport http enterspeed-query "https://mcp.query.enterspeed.com/"

That writes the server into .gemini/settings.json in the current project. Add --scope user to write it into ~/.gemini/settings.json for every project instead. The equivalent by hand is this.

{
  "mcpServers": {
    "enterspeed-query": {
      "httpUrl": "https://mcp.query.enterspeed.com/"
    }
  }
}

Use httpUrl rather than a bare url. Older Gemini CLI releases, and Gemini CLI’s configuration reference, treat url as the older SSE transport, which this server does not speak.

Run /mcp inside the CLI to check the server is listed, and /mcp auth enterspeed-query to complete the sign in.

copilot mcp add --transport http enterspeed-query "https://mcp.query.enterspeed.com/"

That writes the server into ~/.copilot/mcp-config.json. The equivalent by hand is this.

{
  "mcpServers": {
    "enterspeed-query": {
      "type": "http",
      "url": "https://mcp.query.enterspeed.com/",
      "tools": ["*"]
    }
  }
}

"tools": ["*"] offers every tool the server lists. The file needs the tools field, and * is what the command above writes when you give it no --tools. You can add the server interactively instead. Start copilot and run /mcp add. Copilot CLI takes you through the Enterspeed sign in in your browser the first time it connects. If /mcp shows the server as needing authentication, run /mcp auth enterspeed-query.

Web

Claude.ai
ChatGPT

On a Team or Enterprise plan only an Owner can add a custom connector. The Owner adds it under Organization settings, then Connectors. Everyone else finds it under Customize, then Connectors, and clicks Connect.

Open Customize, then Connectors.
Click + and then Add custom connector.
Give it a name, for example Enterspeed Query, and paste https://mcp.query.enterspeed.com/ as the remote MCP server URL.
Click Add, then sign in with your Enterspeed account when Claude asks.

Open Settings, then Security and login, and turn on Developer mode.
Go to ChatGPT Plugins and select the plus button.
Enter a name, and under Connection paste https://mcp.query.enterspeed.com/ as the MCP server URL.
Create the connection, then sign in with your Enterspeed account when ChatGPT asks.
In a chat, choose Developer mode from the plus menu and select the app.

OpenAI offers developer mode to Pro, Plus, Business, Enterprise and Education accounts on the web, and your account or workspace policy can decide whether you have it. If you cannot find Developer mode under Security and login, it is not available to you.

Desktop apps

Claude Desktop uses the same Connectors steps as Claude.ai, including the note for Team and Enterprise plans. The only difference is that after you click Add, the sign-in opens in a browser window.

The Connectors screen cannot send an x-api-key header. To connect Claude Desktop with a scoped key, use its config file and the mcp-remote bridge, as shown under Using a scoped key instead.

IDEs

Cursor
VS Code

Cursor reads MCP servers from ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one.

{
  "mcpServers": {
    "enterspeed-query": {
      "url": "https://mcp.query.enterspeed.com/"
    }
  }
}

A remote server is identified by url, and there is no type field to set. Cursor takes you through the Enterspeed sign in in your browser when it first connects.The Add to Cursor button in the Management App adds the same entry for you. It opens this link.

cursor://anysphere.cursor-deeplink/mcp/install?name=enterspeed-query&config=eyJ1cmwiOiJodHRwczovL21jcC5xdWVyeS5lbnRlcnNwZWVkLmNvbS8ifQ%3D%3D

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": {
    "enterspeed-query": {
      "type": "http",
      "url": "https://mcp.query.enterspeed.com/"
    }
  }
}

Reload the window (Developer: Reload Window) and open the Copilot chat pane. VS Code prompts you to sign in to Enterspeed the first time it connects, and the Enterspeed tools appear in the tool picker afterwards.The Add to VS Code button in the Management App adds the same server for you. It opens this link.

vscode:mcp/install?%7B%22name%22%3A%22enterspeed-query%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.query.enterspeed.com%2F%22%7D

Other MCP clients

The server works with any MCP client that can open a remote Streamable HTTP server and follow an OAuth sign in. Point it at the root URL above. If a client cannot open a remote server, or does not complete the sign in, put mcp-remote in front of it. Configure it as a local command, npx -y mcp-remote "https://mcp.query.enterspeed.com/", and the bridge handles the remote connection and the sign in for the client.

After you connect

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. It does not say 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 your client to select your context is enough. It picks the only one available. The first selection in an environment asks your permission to create the environment client that signing in relies on, and the first query needs a short wait after it is created. A selection can also need repeating after a reconnect. See what to expect when you sign in.

Using a scoped key instead

A scoped environment client key is the other way to connect. 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 the index scope you gave the key. Nobody has to select a context, and the agent cannot reach beyond what the key allows. The key needs the Query API and MCP Server scopes at minimum, and your client sends it in an x-api-key header. See Creating a scoped key.

VS Code
Claude Code
Claude Desktop
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"

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_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. The Connectors screen cannot send an x-api-key header, so this is the route that carries a scoped 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 clients with a key

Any MCP client that can set a custom HTTP header can use a key. Point it at https://mcp.query.enterspeed.com/ with the http transport and set the x-api-key header. These are known to work.

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 cannot set a header, sign in instead. As a last resort you can pass the key as an ?apiKey= query string parameter on the MCP URL. Avoid that in production, because the key ends up in request logs along the whole path.

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, with a key	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).
Signed in, but no tools for your indexes	No context is selected yet, or the client has not listed its tools again since you selected one	Select a context, then have the client list its tools again in the same session. Don’t quit and relaunch, because a new session starts without a context and shows only the static tools.
`401` on every request	The client is not signed in and sends no key	Reconnect and complete the sign in, or send a scoped key in the `x-api-key` header.
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.
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 only when you sign in, because 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 Customize → 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

Connect by signing in

Agent CLIs

Web

Desktop apps

IDEs

Other MCP clients

After you connect

Using a scoped key instead

Project setup

Program.cs

Keeping costs under control

Other clients with a key

Troubleshooting

Next steps

​Connect by signing in

​Agent CLIs

​Web

​Desktop apps

​IDEs

​Other MCP clients

​After you connect

​Using a scoped key instead

​Project setup

​Program.cs

​Keeping costs under control

​Other clients with a key

​Troubleshooting

​Next steps

Connect by signing in

Agent CLIs

Web

Desktop apps

IDEs

Other MCP clients

After you connect

Using a scoped key instead

Project setup

Program.cs

Keeping costs under control

Other clients with a key

Troubleshooting

Next steps