Azure DevOps Remote MCP – How to set X-MCP-Insiders header from a Foundry Prompt Agent/Toolbox?

Question

Azure DevOps Remote MCP – How to set X-MCP-Insiders header from a Foundry Prompt Agent/Toolbox?

csensoft 0

I am using an Azure AI Foundry Agent Service Prompt Agent with a Toolbox that contains the Azure DevOps Remote MCP tool.

I need to query Azure DevOps work items using Board Lane (Swimlane). The standard work-item search tools exposed by the MCP server do not provide a Board Lane filter.

According to the Azure DevOps Remote MCP documentation, the wit_query_by_wiql tool supports arbitrary WIQL queries, which would allow me to query System.BoardLane. However, this tool is currently available only when the following MCP header is supplied:

X-MCP-Insiders: true

The documentation shows how to configure this header for MCP clients such as VS Code, but I cannot find a way to configure arbitrary/custom MCP headers when using:

Foundry Prompt Agent → Toolbox → Azure DevOps Remote MCP

I also checked the Custom MCP configuration in Foundry, but I do not see an option for specifying additional HTTP headers.

My questions are:

Is there currently a supported way to pass X-MCP-Insiders: true to the Azure DevOps Remote MCP when it is used through a Foundry Prompt Agent/Toolbox?

Can custom MCP headers be configured programmatically for a Prompt Agent or Toolbox if they cannot be configured through the Foundry portal?

Is X-MCP-Insiders currently intended primarily for clients where the MCP connection is controlled directly, such as VS Code or Agent Framework/Hosted Agents?

If this is not currently supported for Prompt Agents, is there another supported way to execute arbitrary WIQL/Board Lane queries through the Azure DevOps Remote MCP?

The specific scenario I need to support is equivalent to:

System.TeamProject = 'Constco' AND System.BoardLane = '<lane name>' AND System.State = 'In Development'

I would prefer to continue using the managed Prompt Agent + Toolbox + Azure DevOps Remote MCP architecture rather than introduce a custom Azure DevOps/WIQL tool solely for Board Lane queries.

Manish Deshpande 8,215 Reputation points Microsoft External Staff Moderator

2026-09-18T20:34:04.32+00:00

Hello

Thank you for reaching out to Microsoft Q&A

We have begun looking into it and will share our suggestions with you as soon as possible. If you have any additional details or concerns in the meantime, please let us know. We appreciate your patience while we work on this.

1 answer

Your answer

Manish Deshpande 8,215 Reputation points Microsoft External Staff Moderator

2026-09-18T20:34:04.32+00:00

Hello

Thank you for reaching out to Microsoft Q&A

We have begun looking into it and will share our suggestions with you as soon as possible. If you have any additional details or concerns in the meantime, please let us know. We appreciate your patience while we work on this.

Answer 1

There are two related capabilities here that are easy to conflate.

Microsoft's Azure DevOps Remote MCP documentation currently marks "wit_query_by_wiql" as an MCP Insiders capability and explicitly requires:

"X-MCP-Insiders: true"

At the same time, Microsoft Foundry's general remote MCP implementation does support custom headers. The important limitation is where those headers can be supplied.

For the documented Foundry MCP tool flow, custom headers can be provided at runtime rather than being permanently stored on the MCP tool. Microsoft specifically documents supplying them through the MCP tool resources for the run, and notes that the headers are available only for that run.

That means I would distinguish between:

a directly controlled remote MCP connection, where the client/runtime can attach "X-MCP-Insiders: true"; and
the managed Prompt Agent → Toolbox → Azure DevOps Remote MCP configuration, where the portal does not currently expose an arbitrary-header field for that built-in connection.

So if you are specifically using the managed Prompt Agent + Toolbox Azure DevOps MCP integration and cannot find a header setting, I would not assume that the generic MCP custom-header capability automatically means that this managed connector exposes it.

Microsoft's newer Foundry documentation also supports runtime configuration of MCP properties through structured inputs, including routing headers. That may be worth testing if your Prompt Agent architecture allows you to define the MCP tool rather than relying entirely on the preconfigured Azure DevOps Toolbox integration.

The key question is therefore whether "X-MCP-Insiders" is exposed through that specific managed Azure DevOps MCP tool configuration. I do not see Microsoft documentation currently showing a supported portal setting for adding that header to the managed Toolbox integration.

If you need "System.BoardLane" immediately, the supported fallback is Azure DevOps WIQL itself. Azure DevOps exposes a REST API for executing arbitrary WIQL:

"POST https://dev.azure.com/{organization}/{project}/{team}/_apis/wit/wiql?api-version=7.1"

That would allow the query you described without depending on the MCP Insiders-only "wit_query_by_wiql" tool.

So my current interpretation is:

"wit_query_by_wiql" through Azure DevOps Remote MCP: currently requires "X-MCP-Insiders: true".
Generic Foundry remote MCP: supports custom headers.
Managed Prompt Agent + Toolbox Azure DevOps MCP: I cannot find documentation confirming that arbitrary custom headers such as "X-MCP-Insiders" can currently be injected through that managed configuration.
Directly controlled MCP clients/agents: can supply the required header where their MCP connection configuration exposes headers.
If the managed Prompt Agent path cannot expose the header, direct Azure DevOps WIQL remains the practical supported route for Board Lane queries until the MCP tool becomes generally available or the managed integration exposes the header.

I would be interested in Microsoft confirming whether the Toolbox-managed Azure DevOps MCP connection intentionally strips or simply does not expose arbitrary headers, because that determines whether this is a configuration limitation or a current product gap.

Microsoft Learn references:

Azure DevOps Remote MCP Server:

https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server?view=azure-devops&wt.mc_id=studentamb_521824

Microsoft Foundry MCP tools:

https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/model-context-protocol?wt.mc_id=studentamb_521824

Azure DevOps WIQL REST API:

https://learn.microsoft.com/en-us/rest/api/azure/devops/wit/wiql/query-by-wiql?view=azure-devops-rest-7.1&wt.mc_id=studentamb_521824