Foundry + private Search: Is Name or service not known a DNS problem or an auth problem?

Key takeaways

Name or service not known on Search MCP enumeration is a DNS / path failure until proven otherwise.
Healthy indexers, a correct MCP URL, and project managed-identity RBAC can all look fine while the agent data plane cannot resolve privatelink DNS.
Fix private DNS zone links, VNet injection, and the agent egress path before chasing keys or 403s.
Public MCP from a laptop does not prove the Foundry agent runtime can resolve the private Search hostname.
Hybrid networking plus Search private-endpoint hostname rewrite is the usual trap.
Split symptoms: DNS errors first; 403 Forbidden only after name resolution succeeds.

I keep seeing the same false trail. Azure AI Search sits behind a as a knowledge-base MCP tool. Indexers are green. The MCP URL looks right. The project managed identity has Search roles. Tool enumeration still dies with Name or service not known. Teams open Entra, rotate keys, and argue about RBAC while the agent data plane never resolved the privatelink name.

Treat that error as DNS until a packet could have reached auth.

Named model: DNS before RBAC

DNS: Can the Foundry agent data path resolve the Search hostname the private endpoint rewrote? Private DNS zone privatelink.search.windows.net linked to the VNet the agent actually uses.
Reachability: After resolution, can that path hit the private endpoint (managed VNet, BYO VNet injection, or peered hybrid path)?
RBAC: Only then do project managed-identity roles, Knowledge Base permissions, and 403 Forbidden become the honest next layer.
Split the symptom: Name or service not known means stop before Entra. 403 Forbidden means name resolution worked and auth or network policy is next.
Contract: Laptop curl on a public MCP endpoint is not staging proof for a private agent runtime.

Figure 1. Named model: DNS before RBAC. Prove name resolution and the private path before you chase managed-identity roles or keys.

Context and constraint

The constraint is hybrid and private by design. Search has a private endpoint. The public hostname rewrites toward privatelink DNS. Microsoft Foundry Agent tool enumeration (knowledge-base MCP) runs on a data-plane path that is not your laptop and often not the same resolver your portal session uses.

Community threads on Microsoft Q&A describe the same flip: public or semi-open setups can surface 403 Forbidden; after locking Search to private endpoints, the error becomes Name or service not known even when roles look correct. That is the cue. Resolution failed before auth mattered.

Foundry private-link guidance and agent data-proxy reachability notes point the same way: the runtime needs a VNet path that can resolve and route to the private Search endpoint. Trusted-services checkboxes and portal green lights do not substitute for that path.

Design

1. Read the error literally

Name or service not known is getaddrinfo failing. The process never obtained an IP. RBAC is not in play yet. Do not start with role assignments when the name did not resolve.

2. Inventory the private DNS contract

For Azure AI Search private endpoints you need the privatelink zone linked to every VNet that must resolve the service name, including the network Microsoft Foundry agents actually egress through (managed network, injected BYO VNet, or peered hub). Forgetting the VNet link on privatelink.search.windows.net is a classic miss: portal DNS looks fine from a jump box in another VNet while the agent subnet still uses public resolution that no longer reaches the locked service.

3. Draw the agent path, not the admin path

Admins test from VPN or bastion. Agents enumerate tools through the Foundry data plane / data proxy path. Those resolvers differ. Figure 2 is the simplified private Search MCP path: Search PE, privatelink DNS, Foundry agent runtime. No real hostnames required to teach the shape.

Figure 2. Private Search MCP path. The agent data plane must resolve privatelink DNS and reach the Search private endpoint. A healthy indexer and a laptop-proven URL do not prove that path.

4. Prove DNS, then reachability, then RBAC

Order of proof:

From a host on the same network plane as the agent runtime, resolve the Search FQDN and confirm it returns the private endpoint address, not a public leftover.
Confirm TCP reachability to that private IP on the Search HTTPS port.
Only then validate project managed identity roles on Search / knowledge resources and re-test MCP tool enumeration.

If step 1 fails, stop. Fix zone links, VNet injection, peering, or custom DNS forwarding. Do not rotate API keys.

5. Split DNS symptoms from 403 symptoms

Figure 3 is the symptom split. Use it in incident chat so nobody "fixes" the wrong layer.

Figure 3. Symptom split. Name or service not known stays on DNS and path. 403 Forbidden means resolution worked; now check identity, roles, and allowlists.

6. Keep public laptop success out of the MVP checklist

Public MCP from a developer machine proves the knowledge base and URL shape. It does not prove private DNS links, agent VNet injection, or hybrid resolver chains. Label that test as POC-only in the runbook.

Failure modes

Misreading DNS as 403. Teams paste role docs into the thread while getaddrinfo is still failing.

Fixing keys while the private endpoint remains. New keys never help a name that does not resolve.

Public MCP works from a laptop; agent runtime fails. Different resolver, different network plane, same false confidence.

Forgetting the VNet link on privatelink.search.windows.net. Zone exists; the agent VNet is not linked; symptoms look random.

Trusted services checkbox as a PE substitute. Useful in some public-restricted patterns; not a replacement for private DNS when Search is private-endpoint-only.

Chasing MCP URL typos after PE rewrite. URL hygiene matters, but after a PE cutover the dominant failure is resolution and path, not a missing slash.

What to copy / what not to copy

Copy

Explicit order: DNS, reachability, then RBAC for private Search MCP behind Foundry agents.
Private DNS zone inventory with VNet links for every agent egress network.
A runbook row that rejects laptop-public MCP as staging proof for private MVP.
Symptom language that keeps Name or service not known out of the Entra lane.
Alignment with Foundry private-link / networking overview before custom proxy folklore.

Do not copy blindly

Private Search plus Foundry agents costs networking ownership: DNS, peering, and sometimes managed-network templates. Skipping that ownership keeps demos fast and agent tool lists empty. Opening Search publicly "just for Foundry" undoes the PE decision; prefer fixing the private path (BYO VNet templates, managed VNet, or documented hybrid DNS) over re-expanding the attack surface.

Agent Apps: Can You Put a Fabric Data Agent in a Public Web App? (POC public vs MVP private staging)
Microsoft Foundry: Is Deploy as Web App Enough, or Do You Need a Backend Proxy? (identity and egress first)
Secure AI Shells: Should the Browser Talk to Foundry, or Only Through a Proxy? (secure proxy boundary)

Sources (community grounding): Unable to connect Foundry to Azure AI Search knowledge base, Foundry Agent Service data proxy cannot reach resources, Configure private link for Microsoft Foundry.

Prove DNS. Then reachability. Then RBAC. The agent will not thank you for beautiful role assignments on a name it never resolved.