> ## Documentation Index > Fetch the complete documentation index at: https://docs.enterspeed.com/llms.txt > Use this file to discover all available pages before exploring further. # Connecting a client > Connect Claude Code, Codex, Gemini CLI, Copilot CLI, Claude.ai, ChatGPT, Claude Desktop, Cursor or VS Code to the Enterspeed Query MCP Server by signing in, or use a scoped key. 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](#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](#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`](https://www.npmjs.com/package/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 ```bash theme={null} 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. ```bash theme={null} 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`. ```bash theme={null} 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. ```json theme={null} { "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. ```bash theme={null} 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. ```json theme={null} { "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 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**. 1. Open **Customize**, then **Connectors**. 2. Click **+** and then **Add custom connector**. 3. Give it a name, for example `Enterspeed Query`, and paste `https://mcp.query.enterspeed.com/` as the remote MCP server URL. 4. Click **Add**, then sign in with your Enterspeed account when Claude asks. 1. Open **Settings**, then **Security and login**, and turn on **Developer mode**. 2. Go to **ChatGPT Plugins** and select the plus button. 3. Enter a name, and under **Connection** paste `https://mcp.query.enterspeed.com/` as the MCP server URL. 4. Create the connection, then sign in with your Enterspeed account when ChatGPT asks. 5. 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](#web), 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](#using-a-scoped-key-instead). ### IDEs Cursor reads MCP servers from `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one. ```json theme={null} { "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. ```json theme={null} { "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](/enterspeed/mcp-server/query-mcp/overview#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](/enterspeed/mcp-server/query-mcp/overview#index-scopes) 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](/enterspeed/mcp-server/query-mcp/overview#creating-a-scoped-key). 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. ```json theme={null} { "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](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration) so VS Code prompts for the key on first use, or put the config in your user profile instead of the workspace. ```bash theme={null} 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: ```bash theme={null} 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`](https://www.npmjs.com/package/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: ```json theme={null} { "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 ` 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`](https://www.nuget.org/packages/Anthropic.SDK) for the Messages API and [`ModelContextProtocol`](https://www.nuget.org/packages/ModelContextProtocol) for the MCP session. ```bash theme={null} 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 ```csharp theme={null} 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() .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 { ["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 { 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()) { var args = block.Input.Deserialize>() ?? new(); var mcpResult = await mcp.CallToolAsync(block.Name, args); messages.Add(new Message { Role = RoleType.User, Content = new List { new ToolResultContent { ToolUseId = block.Id, Content = mcpResult.Content.FirstOrDefault()?.Text ?? string.Empty } } }); } } ``` Run it: ```bash theme={null} 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](/enterspeed/mcp-server/query-mcp/overview) — sample prompts and scope reference. * [Connecting an agent](/enterspeed/mcp-server/query-mcp/connecting-an-agent) — Azure AI Foundry and custom-agent wiring. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.