Foundry Agent Service + Search KB MCP tool fails with masked errors (401/405) during agent invocation

[anihitk07]

Summary

When following the Episode 1 cookbook to connect Foundry Agent Service to an Azure AI Search knowledge base via MCP, agent invocation fails in responses.create(...) with tool_user_error. We observed multiple failures that appear to be partially masked by Foundry, making root cause diagnosis difficult.

cc: @farzad528 (Farzad Sunavala)

Environment

• Repo: microsoft/iq-series
• Notebook: 1-Foundry-IQ-Unlocking-Knowledge-for-Agents/cookbook/foundry-iq-cookbook.ipynb
• API versions used in notebook:
  • Search KB MCP endpoint: api-version=2025-11-01-preview
  • Project connection ARM call: api-version=2025-10-01-preview
• SDKs:
  • azure-search-documents==11.7.0b2
  • azure-ai-projects

What we observed

1) Initial retrieval errors (direct KB retrieve path)

• Serialization issue fixed by using:
  • retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort()
• Then got 404 from model endpoint due to AOAI endpoint format (.../openai/v1 suffix). Normalizing to base resource endpoint fixed this.
• Then got 401 indicating missing data action for principal:
  • xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (managed identity for search service)

2) Step 5 (Foundry Agent + MCP tool) errors

• First failure:
  • Connection 'earth-kb-mcp-connection' not found.
  • Root cause: project mismatch between FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_PROJECT_RESOURCE_ID (resolved by aligning both to same project).
• Current failure after project alignment:
  • Error encountered while enumerating tools from remote server .../knowledgebases/earth-knowledge-base/mcp. Details: Response status code does not indicate success: 405 (Method Not Allowed).

Key diagnostics

• Connection now exists in the same Foundry project and points to:
  • https://xxxx.search.windows.net/knowledgebases/earth-knowledge-base/mcp?api-version=2025-11-01-preview
• Manual protocol checks against MCP endpoint:
  • GET to MCP endpoint -> 405
  • JSON-RPC POST tools/list to same endpoint -> succeeds and returns knowledge_base_retrieve

This suggests a transport/protocol mismatch in tool enumeration path (or a masked underlying permission error) when Foundry invokes the remote MCP server.

Request

Could the team please investigate the Foundry↔Search MCP integration behavior here, especially:

1. Whether Foundry tool enumeration is using an unsupported method/headers for this MCP endpoint.
2. Whether Foundry is masking underlying authorization failures from Search and surfacing only generic 405 tool_user_error.
3. Any required role assignments specifically for project managed identity vs search managed identity in this integration path.

Happy to provide additional logs/correlation IDs if needed.

[farzad528]

Thanks for filing this @anihitk07 — this is a known active bug where Foundry Agent Service masks the underlying error from Azure AI Search and surfaces generic tool_user_error / 405 messages instead. The root cause is almost always an authentication/authorization issue between the Foundry project's managed identity and the Azure AI Search service.

---

🔐 RBAC Requirements Checklist

When using keyless (Microsoft Entra ID) authentication for the Foundry ↔ Azure AI Search connection, the following role assignments are required on the Azure AI Search service:

Role	Assigned To	Purpose
Search Index Data Contributor	Foundry project managed identity	Read/write access to index data (docs)
Search Service Contributor	Foundry project managed identity	Manage search service resources (docs)

Additionally, if the knowledge base uses an LLM (e.g., for query planning or answer synthesis):

Role	Assigned To	Where
Cognitive Services User	Azure AI Search service managed identity	On the Microsoft Foundry resource (docs)

How to assign these roles:

1. Go to the Azure Portal → your Azure AI Search resource
2. Settings > Keys → Select Both (enables RBAC + key-based auth)
3. Access control (IAM) → Add role assignment → assign the roles above to your Foundry project's managed identity

⚠️ Make sure FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_PROJECT_RESOURCE_ID point to the same project (as you discovered with the connection mismatch).

---

🔍 How to Isolate: Query the Knowledge Base Directly

To confirm whether the problem is on the search side vs. the Foundry agent side, you can query the knowledge base directly using the Retrieve REST API — bypassing Foundry entirely.

Option 1: REST API (with API key)

POST https://<your-search-service>.search.windows.net/knowledgebases/<your-kb-name>/retrieve?api-version=2025-11-01-preview
Content-Type: application/json
api-key: <your-admin-key>

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "test query here" }
            ]
        }
    ],
    "includeActivity": true
}

Option 2: Python SDK

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
)

kb_client = KnowledgeBaseRetrievalClient(
    endpoint="https://<your-search-service>.search.windows.net",
    knowledge_base_name="<your-kb-name>",
    credential=AzureKeyCredential("<your-api-key>"),
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="test query here")],
        )
    ],
    include_activity=True,
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

Option 3: MCP endpoint directly (JSON-RPC POST)

You already confirmed that POST with tools/list works against the MCP endpoint. You can also test tools/call with knowledge_base_retrieve:

POST https://<your-search-service>.search.windows.net/knowledgebases/<your-kb-name>/mcp?api-version=2025-11-01-preview
Content-Type: application/json
api-key: <your-admin-key>

{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
        "name": "knowledge_base_retrieve",
        "arguments": {
            "query": "test query here"
        }
    },
    "id": 1
}

If the direct query succeeds → the issue is in how Foundry Agent Service authenticates/invokes the MCP server (which aligns with the error masking bug).

If the direct query fails with 401 → the RBAC roles above need to be checked/re-assigned.

---

📚 Relevant Documentation

• Query a knowledge base using retrieve action or MCP endpoint
• Connect Azure AI Search to Foundry agents (RBAC setup)
• Tutorial: End-to-end agentic retrieval pipeline

We're tracking this error masking behavior. Will update this issue as we get more clarity from the Foundry Agent Service team on the 405 during tool enumeration.

[farzad528]

Hi @anihitk07 - circling back on this. The masked 405 (Method Not Allowed) / 401 you saw during agent tool enumeration is a Foundry-side error-masking behavior: the real failure is almost always RBAC/configuration between the Foundry Agent and the Azure AI Search knowledge base MCP endpoint, not a transport bug. That is why the surfaced error is so confusing.

I have hardened Episode 1 in #50 with a dedicated Troubleshooting the agent + MCP connection section that walks through the exact things to check:

• RBAC roles on the Search service for the Foundry project's managed identity (Search Index Data Reader + Search Service Contributor), plus Cognitive Services User for the Search MI on the AOAI/Foundry resource.
• Keeping FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_PROJECT_RESOURCE_ID pointed at the same project (mismatches surface as Connection '...' not found).
• Using the base AOAI endpoint (https://<resource>.openai.azure.com, with no /openai/v1 suffix).
• Querying the KB directly via retrieval_client.retrieve(...) to isolate whether the issue is search vs. agent auth.

I also upgraded the series to azure-search-documents==12.1.0b1 and validated the full agent + MCP flow end-to-end against live Azure. The agent returns a cited answer once the roles above are in place.

Please pull #50, run through the troubleshooting checklist, and let me know if anything still trips up. Thanks for your patience on this one!