Foundry Portal strips query parameters from MCP endpoint URL during tool enumeration, causing 406 NotAcceptable error

[shweta0310]

Description

When adding an MCP (Model Context Protocol) tool to an agent via the Foundry portal, the portal fails to list tools from an Azure AI Search Knowledge Base MCP endpoint. The portal strips the required ?api-version= query parameter from the endpoint URL when probing the server, causing a 406 NotAcceptable error.

The MCP connection is saved correctly, but the MCP tool is never attached to the agent because the portal blocks on the tool enumeration failure.

Workaround: Adding the MCP tool directly to the agent definition via the Foundry Agent REST API works — the tool functions correctly at runtime.

Steps to Reproduce

1. Create an Azure AI Search Knowledge Base with an MCP endpoint:

   https://<search-service>.search.windows.net/knowledgebases/<kb-name>/mcp**?api-version=2025-11-01-Preview**
   

2. In the Foundry portal, open an agent and click Add tool → MCP (Model Context Protocol)
3. Fill in the dialog:
   • Name: src-supplier-kb-mcp
   • Remote MCP Server endpoint: https://<search-service>.search.windows.net/knowledgebases/<kb-name>/mcp?api-version=2025-11-01-Preview
   • Authentication: Microsoft Entra
   • Type: Project Managed Identity
   • Audience: https://search.azure.com
4. Click Connect

Expected Behavior

The portal should call the MCP endpoint with the full URL including query parameters to enumerate available tools (e.g., knowledge_base_retrieve), then attach the MCP tool to the agent definition.

Actual Behavior

The portal strips the ?api-version=2025-11-01-Preview query parameter and calls:

https://<search-service>.search.windows.net:443/knowledgebases/<kb-name>/mcp

Azure AI Search requires the api-version parameter on all requests and returns 406 NotAcceptable without it.

The error displayed in the portal:

Error encountered while enumerating tools from remote server:
https://<search-service>.search.windows.net:443/knowledgebases/<kb-name>/mcp.
Details: Response status code does not indicate success: 406 (NotAcceptable).

However, the portal does successfully create the project connection (verified via Management API — see below). It just fails to proceed to the tool-binding step.

Workaround — REST API

The MCP tool can be successfully added by POSTing a new agent version directly via the Foundry Agent REST API:

POST https://<foundry-resource>.services.ai.azure.com/api/projects/<project>/agents/<agent-name>?api-version=v1
Authorization: Bearer <token with audience https://ai.azure.com>
Content-Type: application/json

{
    "definition": {
        "kind": "prompt",
        "model": "gpt-4.1",
        "instructions": "<existing instructions>",
        "tools": [
            {
                "type": "file_search",
                "vector_store_ids": ["<existing-vector-store-id>"]
            },
            {
                "type": "mcp",
                "server_label": "src-supplier-kb-mcp",
                "server_url": "https://<search-service>.search.windows.net/knowledgebases/<kb-name>/mcp?api-version=2025-11-01-Preview",
                "require_approval": "never",
                "allowed_tools": ["knowledge_base_retrieve"]
            }
        ]
    }
}

This returns 200 OK and creates a new agent version with the MCP tool attached. At runtime, the agent successfully calls knowledge_base_retrieve MCP tool because the full URL (with query parameter) is preserved.

Verification — Connection is created correctly by portal

Listing project connections via Management API confirms the portal creates the connection with the correct URL:

GET https://management.azure.com/.../projects/<project>/connections?api-version=2025-10-01-preview

Response shows:

Name: src-supplier-kb-mcp
Category: RemoteTool
Target: https://<search-service>.search.windows.net/knowledgebases/<kb-name>/mcp?api-version=2025-11-01-Preview

The connection URL is correct — the query parameter is only stripped during the tool enumeration probe.

Environment

• Foundry portal: Microsoft Foundry (portal accessed April 2026)
• Azure AI Search: API version 2025-11-01-Preview, Knowledge Base with MCP endpoint
• Agent API: v1
• Search service region: Central US
• Authentication: Microsoft Entra with Project Managed Identity

Root Cause Analysis

Microsoft Foundry Portal's MCP tool dialog appears to parse the endpoint URL and strip query parameters before making the tool enumeration call. Azure AI Search requires api-version on all API calls — without it, the service returns 406 NotAcceptable.

The issue is specifically in the portal's enumeration/probe logic, not in the connection creation or the agent runtime. The runtime correctly uses the full URL.

Impact

• Users cannot add Azure AI Search Knowledge Base MCP tools to agents via the portal UI
• Users must use the REST API as a workaround, which requires knowledge of the exact tool schema format
• The portal shows a misleading error that suggests the connection itself is broken, when in reality only the query parameter is missing

Suggested Fix

Preserve the full URL (including all query parameters) when the Foundry Portal calls the MCP endpoint for tool enumeration. The server_url should be used as-is without modification, like removal of query-parameters from the URL.

Additional Context

• The portal also showed a "Timeout enumerating tools" error on the first attempt before showing the 406 on retry — likely the same root cause (the request without api-version may hang or get a slow rejection from the search service).
• When an MCP connection already exists from a failed attempt, trying again shows "Connection name must be unique" — users need to either delete the orphaned connection via REST or use a different name.