Foundry IQ knowledge base works on direct /retrieve but fails via agent MCP tool — "Only Azure OpenAI and Azure AI Foundry endpoints are supported for Knowledge Base model configurations"

Boboc Vlad 0 Reputation points
2026-08-19T16:43:19.3166667+00:00

I have a Foundry Agent Service agent with a Foundry IQ knowledge base over an Azure AI Search index. It was working in early July 2026 and stopped working in August with no change on my side.

Every agent turn that hits the knowledge base fails:


An error occurred invoking 'knowledge_base_retrieve': BadRequest

{"Message":"Only Azure OpenAI and Azure AI Foundry endpoints are supported for Knowledge

Base model configurations. API Management (APIM) and custom domain endpoints are not

supported.","DataPlaneErrorCode":5,"DataPlaneErrorDetail":[{"Code":71,...}]}

I use neither APIM nor a custom domain.

The core observation

The same knowledge base returns HTTP 200 when I call it directly, and HTTP 400 when the agent calls it through MCP.

Direct call, authenticated with the search admin key — returns 200 with correct grounded content:


curl -X POST \

  "https://<search-service>.search.windows.net/knowledgeBases/<kb-name>/retrieve?api-version=2026-05-01-preview" \

  -H "api-key: <ADMIN_KEY>" \

  -H "Content-Type: application/json" \

  -d '{"intents":[{"type":"semantic","search":"termination clause"}]}'

Same knowledge base via the agent's MCP tool (server_url = https://<search-service>.search.windows.net/knowledgebases/<kb-name>/mcp?api-version=2026-05-01-preview, auth ProjectManagedIdentity) — 400, message above.

The only difference between the two paths is authentication to the search service: api-key vs ProjectManagedIdentity (audience https://search.azure.com).

The error does not respond to any KB model configuration change

I changed models[0].azureOpenAIParameters eight times. The agent-side error text was identical every single time, with a new RequestId each time:

| resourceUri | Deployment | Credential | Direct | Via agent |

|---|---|---|---|---|

| <foundry-res>.openai.azure.com | gpt-5.4-mini | apiKey | — | 400 |

| <foundry-res>.cognitiveservices.azure.com | gpt-5.4-mini | apiKey | — | 400 |

| <foundry-res>.services.ai.azure.com | gpt-5.4-mini | apiKey | 400 | 400 |

| <openai-res>.openai.azure.com | gpt-4o | apiKey | 200 | 400 |

| <openai-res>.openai.azure.com | gpt-5.4-mini | apiKey | 200 | 400 |

| same, effort minimal | gpt-5.4-mini | apiKey | 200 (intents) | 400 |

| same | gpt-5.4-mini | apiKey: null, authIdentity: null | 400 | 400 |

| same | gpt-5.4-mini | both fields absent (system-assigned MI) | 200 | 400 |

The last row is my current state: a native Azure OpenAI resource (kind: OpenAI), a supported gpt-5.4-mini deployment, authenticating via the search service's system-assigned managed identity which holds Cognitive Services OpenAI User on that resource. It returns 200 directly and still fails via the agent.

That makes me suspect the MCP knowledge_base_retrieve path does not use the model configuration stored on the knowledge base, but one resolved from the Foundry project's parent resource — which in my case is of kind AIServices, so its endpoints are on *.cognitiveservices.azure.com / *.services.ai.azure.com. Those look like exactly the endpoints the validator rejects.

The obvious workaround appears to be blocked

I created an Azure OpenAI project connection to the native OpenAI resource and deployed gpt-5.4-mini there, intending to point the agent's model at it. The portal then shows:

Model deployments from connected project resources can't be used with Agents. To use these deployments, use AI Gateway.

The agent YAML confirms it — definition.model is a bare deployment name with no connection reference, so it always resolves against the project's own AIServices resource.

If my reading is right, there is no valid configuration for a Foundry project hosted on an AIServices resource that wants to use a Foundry IQ knowledge base.

Side note — the error message is misleading

On the direct path, the same "endpoints are not supported" message appears whenever the model configuration has no usable credential. Compare the last two rows above: setting apiKey and authIdentity to explicit null gives this endpoint error, while removing both fields entirely succeeds via managed identity. The message describes a host problem when the actual condition is a missing credential. This cost me most of a day.

What I verified as healthy

  • Index and semantic configuration — direct retrieval returns correct, relevant content.
  • Knowledge source — searchIndex kind, no model configuration of its own.
  • Project connection for the MCP tool — target is the MCP endpoint on search.windows.net, no model reference.
  • RBAC — both the search service's system-assigned identity and the Foundry project identity hold Cognitive Services OpenAI User on the Azure OpenAI resource.
  • Agent YAML — MCP server_url is correct.

Questions

  1. Which model endpoint does the MCP knowledge_base_retrieve path actually resolve and call — the one stored on the knowledge base, or one derived from the project's parent resource?
  2. Can a Foundry project on a resource of kind AIServices use Foundry IQ knowledge bases under the current validation rules? If not, is a project on a native Azure OpenAI resource the required topology?
  3. Was there a server-side validation change to Foundry IQ knowledge base model configurations between early July and mid-August 2026?
  4. Is there a supported configuration that restores this without re-platforming the project?

RequestIds


2eb8669d-ac69-496e-99ae-7f361232b105

c73f680f-7a31-4d0b-b979-72e80f852ca5

493d355f-de07-4947-a101-cde03badcb27

I have six more from earlier attempts, plus subscription and resource details, and can share them privately if a moderator needs them.

Region is Sweden Central, API version 2026-05-01-preview throughout.

Thanks for any pointers.

Foundry Agent Service
Foundry Agent Service

A fully managed platform in Microsoft Foundry for hosting, scaling, and securing AI agents built with any supported framework or model

0 comments

2 answers

Sort by: Oldest
Most helpful Newest Oldest
  1. Abinesh Magudeeswaran 90 Reputation points Student Ambassador
    2026-08-19T17:45:09.76+00:00

    Hi Vlad,

    Your direct-vs-MCP comparison is useful. Based on the current Microsoft documentation, the MCP configuration itself appears to be the supported integration pattern: the agent connects to the Azure AI Search knowledge base MCP endpoint using a RemoteTool project connection with ProjectManagedIdentity, and the supported MCP tool is knowledge_base_retrieve.

    I would therefore focus first on the model configuration that the knowledge base uses during MCP retrieval rather than the Azure AI Search authentication itself.

    A few things stand out:

    • The MCP endpoint should be the Azure AI Search endpoint in the form https://<search-service>.search.windows.net/knowledgebases/<kb>/mcp?api-version=2026-05-01-preview.

    The project connection should use ProjectManagedIdentity with the https://search.azure.com/ audience, which matches the documented configuration.

    Microsoft documents that the knowledge base can use an LLM from Azure OpenAI in Foundry Models for query planning and synthesis.

    Microsoft also documents the same knowledge_base_retrieve MCP integration for Foundry Agent Service, so an AIServices-based Foundry project is not documented as inherently unsupported.

    Because your direct REST request succeeds while the same KB fails only when invoked through the agent, I would collect the following before changing the project topology:

    The complete knowledge base definition, especially its models configuration.

    The exact agent model deployment name.

    The project resource kind and project endpoint.

    The MCP project connection configuration, including authType, audience, and target.

    The exact RequestId from a fresh failed invocation.

    I would also test the same MCP endpoint independently with an Entra bearer token for Azure AI Search. Microsoft recommends bearer-token authentication for the MCP endpoint, although an admin key is also supported.

    One important point: the documentation currently describes the 2026-05-01-preview integration as preview functionality, so a server-side regression or validation change is possible, but I don't see public Microsoft documentation confirming that a July-to-August validation change occurred or that an AIServices parent resource is unsupported.

    Given that your model configuration changes produce the same 400 while direct retrieval continues to work, this looks worth escalating to Microsoft with the RequestIds you collected rather than re-platforming the project immediately.

    The RequestIds and the direct-vs-MCP reproduction steps you provided should give Microsoft Support enough information to trace where the endpoint validation is occurring.Hi Vlad,

    Your direct-vs-MCP comparison is useful. Based on the current Microsoft documentation, the MCP configuration itself appears to be the supported integration pattern: the agent connects to the Azure AI Search knowledge base MCP endpoint using a RemoteTool project connection with ProjectManagedIdentity, and the supported MCP tool is knowledge_base_retrieve.

    I would therefore focus first on the model configuration that the knowledge base uses during MCP retrieval rather than the Azure AI Search authentication itself.

    A few things stand out:

    The MCP endpoint should be the Azure AI Search endpoint in the form https://<search-service>.search.windows.net/knowledgebases/<kb>/mcp?api-version=2026-05-01-preview.

    The project connection should use ProjectManagedIdentity with the https://search.azure.com/ audience, which matches the documented configuration.

    Microsoft documents that the knowledge base can use an LLM from Azure OpenAI in Foundry Models for query planning and synthesis.

    Microsoft also documents the same knowledge_base_retrieve MCP integration for Foundry Agent Service, so an AIServices-based Foundry project is not documented as inherently unsupported.

    Because your direct REST request succeeds while the same KB fails only when invoked through the agent, I would collect the following before changing the project topology:

    The complete knowledge base definition, especially its models configuration.

    The exact agent model deployment name.

    The project resource kind and project endpoint.

    The MCP project connection configuration, including authType, audience, and target.

    The exact RequestId from a fresh failed invocation.

    I would also test the same MCP endpoint independently with an Entra bearer token for Azure AI Search. Microsoft recommends bearer-token authentication for the MCP endpoint, although an admin key is also supported.

    One important point: the documentation currently describes the 2026-05-01-preview integration as preview functionality, so a server-side regression or validation change is possible, but I don't see public Microsoft documentation confirming that a July-to-August validation change occurred or that an AIServices parent resource is unsupported.

    Given that your model configuration changes produce the same 400 while direct retrieval continues to work, this looks worth escalating to Microsoft with the RequestIds you collected rather than re-platforming the project immediately.

    The RequestIds and the direct-vs-MCP reproduction steps you provided should give Microsoft Support enough information to trace where the endpoint validation is occurring.

    Was this answer helpful?

    0 comments
  2. Boboc Vlad 0 Reputation points
    2026-08-31T10:17:41.69+00:00

    Thanks — your suggestion to test the MCP endpoint independently with an Entra bearer token was the right call, and it settled the case. Posting the result because it changes the diagnosis substantially.

    The MCP endpoint reproduces the failure with no Foundry agent in the chain.

    Repro is three calls against the knowledge base MCP endpoint, authenticated with an Entra token for https://search.azure.com:

    TOKEN=$(az account get-access-token --resource "https://search.azure.com" --query accessToken -o tsv)
MCP="https://<search-service>.search.windows.net/knowledgebases/<kb>/mcp?api-version=2026-05-01-preview"
H=(-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream")

# 1) handshake -> HTTP 200, valid serverInfo
curl -sS -X POST "$MCP" "${H[@]}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# 2) tools/list -> HTTP 200, tool schema returned
curl -sS -X POST "$MCP" "${H[@]}" -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3) tools/call -> isError:true, the endpoint-validation message
curl -sS -X POST "$MCP" "${H[@]}" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"knowledge_base_retrieve","arguments":{"queries":["<query>"]}}}'

    Steps 1 and 2 succeed, so Entra auth against the MCP endpoint is fine. Step 3 returns:

    An error occurred invoking 'knowledge_base_retrieve': BadRequest
{"Message":"Only Azure OpenAI and Azure AI Foundry endpoints are supported for Knowledge
Base model configurations. API Management (APIM) and custom domain endpoints are not
supported.", "DataPlaneErrorCode":5, ...}

    Side-by-side, same knowledge base, same moment:

    Call Result
    POST /retrieve with intents input (admin key or Entra token) HTTP 200, correct grounded content
    -------- --------
    POST /retrieve with intents input (admin key or Entra token) HTTP 200, correct grounded content
    POST /mcp → tools/call knowledge_base_retrieve with queries (Entra token) error, message above

    What this rules out. My earlier hypothesis — that the failure came from the Foundry project's parent resource being of kind AIServices, so the model endpoint resolved to *.cognitiveservices.azure.com / *.services.ai.azure.com — is wrong. You were right to question it, and right about the reason: no documentation supported it. The defect reproduces with no Foundry involvement at all.

    I also tested the follow-up hypothesis that the queries input requires query planning unavailable at retrievalReasoningEffort: minimal. Raised the effort to low, confirmed via GET on the knowledge base, re-ran step 3: fails identically. So the reasoning effort is not the factor either.

    Current state of the invariance. The tools/call failure is unchanged across: three endpoint hostnames, two Azure OpenAI resources (one kind: OpenAI, one kind: AIServices), two model deployments (gpt-4o, gpt-5.4-mini), three credential forms (apiKey set / explicit null / fields absent → system-assigned MI), and two reasoning-effort levels. The knowledge base configuration currently in place returns HTTP 200 on POST /retrieve.

    Secondary finding, possibly relevant. tools/list reports the tool's input schema as queries — "1 to 3 search queries. Each query: max 150 characters; under 12 words." Not intents, not messages. So the MCP path and the REST path take different inputs, and only the MCP one fails. If the MCP handler converts queries into an internal retrieval request, that conversion looks like the place where the model configuration is re-resolved and rejected.

    The question, narrowed to one: why does the MCP tools/call path reject a knowledge base model configuration that POST /retrieve accepts, on the same knowledge base?

    RequestIds from the direct MCP calls (no agent involved):

    9e1e1c7b-2a9e-4f2f-8c4c-2d41c1584414
5b0c2886-b72e-4f2c-9713-e740ffffc212
cd58c2c2-2185-412b-b710-dff4cf2f29ed

    Region Sweden Central, api-version 2026-05-01-preview throughout. Happy to share the full knowledge base definition, connection config and the earlier nine RequestIds privately if a moderator needs them.

    For anyone hitting this: the workaround that restored our agent is to drop the Foundry IQ attachment and call POST /retrieve directly as an OpenAPI tool with intents input, which is unaffected.

    Was this answer helpful?

    0 comments

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.