Free tools Windows power users keep installed
One-click scans. No signup required.
Use Azure AI Search’s Foundry IQ knowledge-base MCP endpoint as a remote tool in LangGraph. A Python application can create an HTTP MultiServerMCPClient, send the Azure Search bearer token in the x-ms-query-source-authorization header, load the exposed knowledge_base_retrieve tool, bind it to a chat model, and route tool calls through a LangGraph ToolNode. The connection is a composition of documented Microsoft and LangChain components; you must still validate endpoint versioning, identity, permissions, tool discovery, and source references in your own environment.
What you are connecting
Foundry IQ knowledge bases are hosted by Azure AI Search. The knowledge base exposes an MCP server, and its retrieval interface is the knowledge_base_retrieve tool. LangGraph acts as the MCP client: it connects over HTTP, discovers the remote tool, gives that tool to the model, and executes tool calls inside the graph.
As an Amazon Associate I earn from qualifying purchases.
The knowledge base can coordinate retrieval across configured knowledge sources. Depending on its configuration, Azure AI Search can plan or decompose a question, run keyword, vector, or hybrid searches, rerank results, and optionally synthesize an answer with source references. Foundry Agent Service is not required for direct calls: an application that supports the Azure AI Search knowledge-base APIs can call the knowledge base itself.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsThis integration does not make LangGraph a special Foundry runtime. Your LangGraph process remains responsible for model invocation, graph state, HTTP connectivity, token acquisition, error handling, and instructions that require retrieval when a question depends on indexed content.
Choose the connection route first
There are two documented ways to expose the knowledge-base retrieval capability to an MCP-compatible client. Select the route that matches where identity and policy should be managed.
| Route | Best fit | What you must operate |
|---|---|---|
| Direct Foundry IQ MCP endpoint | A LangGraph service that can obtain Azure credentials and wants the shortest path to Azure AI Search | Workload or user identity, Search data permissions, token audience and claims, endpoint and preview API version, and secret handling in the application |
| Foundry Toolbox in front of the endpoint | Teams that want a shared MCP entry point, reusable tool configuration, centralized credentials, or policy control | Toolbox configuration, client compatibility, the selected identity mode, and ownership of access policies |
Microsoft documents Toolbox as MCP-compatible with clients including LangGraph, and its hosted-agent quickstart demonstrates a knowledge-base-to-Toolbox arrangement. That documentation does not establish a universal performance or security winner. The practical choice is where you want credentials, authorization policy, and tool configuration to live.
Prerequisites and version checks
- An Azure AI Search service with a Foundry IQ knowledge base and at least one configured knowledge source.
- A Foundry project and a deployed model if your application also uses Foundry model capabilities. The native Foundry connection route does not support hub-based projects.
- Python 3.10 or later for the Microsoft LangChain/LangGraph examples.
- A LangGraph application and the current
langchain-mcp-adapterspackage, plus the LangGraph and LangChain packages required by your chosen model integration. - An MCP client configuration that supports HTTP transport and custom request headers.
- An Azure identity (workload identity, managed identity, service principal, or user identity) with the Search permissions needed to read the knowledge sources.
- A current check of the Azure AI Search knowledge-base MCP API version. Microsoft’s connection example uses the preview version
2026-08-01-preview; preview contracts can change. - If you use Microsoft’s native Python SDK path for other Foundry operations, the connection guide lists
azure-ai-projects>=2.0.0. That package is not required merely because LangGraph consumes a remote MCP tool.
Install package versions from the current LangChain, LangGraph, MCP adapter, and Microsoft documentation rather than pinning an old example. Keep the MCP adapter and LangGraph versions compatible, because tool-loading and graph APIs evolve independently.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Build the direct MCP endpoint URL
The endpoint pattern documented for a Foundry IQ knowledge base is:
https://<search-service>.search.windows.net/knowledgebases/<knowledge-base-name>/mcp?api-version=2026-08-01-previewReplace <search-service> with the Azure AI Search service name and <knowledge-base-name> with the exact knowledge-base resource name. Preserve the hostname, path, and API-version query parameter exactly. A misspelled service hostname or knowledge-base name commonly produces a 400 or 404. Recheck the current Azure AI Search documentation before deployment because the example uses a preview API.
Store the complete URL in an environment variable such as FOUNDRY_IQ_MCP_ENDPOINT. Do not assemble it from user-supplied query text, and do not silently remove the API-version parameter.
Configure authentication deliberately
Pass the Search token in the MCP request header
The Foundry Agent Service example passes a bearer token as structured authorization input. The LangChain MCP adapter supports custom HTTP headers, so a standalone LangGraph host can send the same credential in x-ms-query-source-authorization:
headers = {
"x-ms-query-source-authorization": f"Bearer {search_token}"
}Acquire search_token at runtime with the Azure identity available to the process. Never hard-code a token in source code, commit it to a repository, place it in a prompt, or print it in request logs. Use your deployment platform’s managed identity or workload identity where possible; otherwise use a secret store and rotate credentials according to your organization’s policy.
Give the identity the right Search role
The identity used for retrieval needs Azure AI Search data permissions. Microsoft’s native integration example uses a project managed identity with Search Index Data Reader for read-only index access. Your standalone LangGraph host may use a different identity, but it must receive an equivalent role at the scope required by the knowledge source. Role assignment alone is not enough if the token has the wrong audience, is expired, or lacks the expected claims.
Do not assume hosted-agent identity follows your app
A hosted Foundry agent can use its managed identity when a Toolbox connection is configured. A separately deployed LangGraph service does not automatically inherit that identity. Explicitly decide which principal makes the Search request and verify that principal in the target runtime.
Wire the knowledge-base tool into LangGraph
The following asynchronous wiring pattern follows the documented MCP adapter and LangGraph APIs. It shows the integration shape; it is not a claim that this exact endpoint, model, and identity combination has been tested as one packaged deployment.
import os
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.chat_models import init_chat_model
from langgraph.graph import MessagesState, StateGraph, START
from langgraph.prebuilt import ToolNode, tools_condition
endpoint = os.environ["FOUNDRY_IQ_MCP_ENDPOINT"]
search_token = os.environ["AZURE_SEARCH_TOKEN"]
client = MultiServerMCPClient(
{
"foundry-iq": {
"transport": "http",
"url": endpoint,
"headers": {
"x-ms-query-source-authorization": f"Bearer {search_token}"
},
}
}
)
tools = await client.get_tools()
model = init_chat_model(os.environ["MODEL_NAME"])
bound_model = model.bind_tools(tools)
async def call_model(state: MessagesState):
response = await bound_model.ainvoke(state["messages"])
return {"messages": [response]}
builder = StateGraph(MessagesState)
builder.add_node("call_model", call_model)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "call_model")
builder.add_conditional_edges("call_model", tools_condition)
builder.add_edge("tools", "call_model")
graph = builder.compile()What each part does
MultiServerMCPClientdefines a named MCP server, herefoundry-iq, using HTTP transport.get_tools()performs tool discovery. Confirm that the returned collection containsknowledge_base_retrievebefore accepting user traffic.bind_tools(tools)lets the model emit a tool call when the question needs indexed evidence.ToolNode(tools)executes the discovered MCP tool and places its result back into graph messages.tools_conditionroutes a model response containing a tool call to the tool node; a normal response proceeds to the graph’s end.- The edge from
toolsback tocall_modellets the model read retrieval output and produce the final answer.
Keep the MCP client lifetime appropriate for your server model. For a long-running process, initialize it during application startup and close it according to the adapter version’s lifecycle guidance. For short-lived jobs, create and dispose of it within the job boundary. Avoid creating a new client for every token in a streaming response.
Tell the model when retrieval is mandatory
Tool binding does not guarantee tool use. Add explicit model instructions for questions whose answers depend on the knowledge base. A useful policy tells the model to:
- Call
knowledge_base_retrievefor organization-specific, indexed, or otherwise knowledge-base-dependent facts. - Separate retrieved evidence from general model knowledge.
- Use the returned source references when making factual claims.
- State clearly when retrieval returns no supporting evidence instead of filling the gap with an invented answer.
- Avoid claiming that a document was consulted when the tool was not called.
These instructions improve consistency and source attribution, but they do not replace authorization. A prompt cannot grant access to documents the Search identity is not allowed to read.
Understand query planning and retrieval behavior
Foundry IQ uses Azure AI Search agentic retrieval. It can search multiple configured sources and combine keyword, vector, or hybrid retrieval with reranking. Optional LLM query planning can decompose a complex question into subqueries. Microsoft’s FAQ says query planning is required for parallel processing of multiple subqueries; without it, minimal retrieval reasoning can still merge results from multiple sources.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →The documented query-planning model choices include Azure OpenAI models in Foundry Models’ gpt-4o, gpt-4.1, and gpt-5 series at the time of that documentation. Confirm the currently supported deployments before selecting one, because model availability and supported versions can change.
Retrieval and answer synthesis are distinct concerns. The knowledge base may return passages and references, while the LangGraph model decides how to explain them. Preserve the tool result and its source metadata in the message flow so your application can display or audit citations.
Use a Toolbox when centralized control matters
A Foundry Toolbox can sit in front of the knowledge-base MCP endpoint and provide a reusable MCP connection for compatible clients. This route is useful when several applications should consume the same tool configuration, when credentials should be managed centrally, or when an operations team owns access policy separately from application code.
Configure the Toolbox connection and identity according to the current Foundry quickstart, then point the LangGraph MCP client at the Toolbox MCP endpoint. Keep the same validation steps as the direct route: discover the expected retrieval tool, verify the effective principal, inspect source references, and test denied access. A Toolbox does not make an arbitrary LangGraph process inherit the managed identity of a hosted Foundry agent.
Document-level permissions need explicit verification
Do not infer document security from the existence of an index or knowledge source. Microsoft’s FAQ says document-level permissions are enforced only when the knowledge source supports them and permissions are explicitly configured for synchronization, unless that source’s documentation specifies another mechanism.
Review the permission configuration for every source, identify which principal is synchronized, and test with identities that should and should not see the same document. Verify the runtime identity rather than testing only with an administrator. If your source does not support document-level controls, enforce access at the application or source boundary instead of presenting retrieval as user-specific authorization.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Validate the connection before exposing it to users
- Check configuration. Confirm the endpoint uses the correct Search hostname, exact knowledge-base name, and currently supported API version.
- Check token acquisition. Obtain a token from the identity used by the deployed LangGraph process and inspect its audience and expiration without logging the token value.
- Check Search permissions. Verify the principal has the required Search data role at the relevant scope.
- Check MCP discovery. Run
get_tools()and fail startup or health checks ifknowledge_base_retrieveis missing. - Check a grounded question. Ask about a distinctive fact present in a known source and confirm that the tool is called.
- Check references. Ensure retrieval output retains source identifiers or citations and that the final response uses them when appropriate.
- Check an unsupported question. Confirm the model says the knowledge base does not support an answer rather than fabricating one.
- Check denial behavior. Test an identity without the required Search role and verify that the application returns a controlled error without leaking indexed content.
- Check operational logs. Record request IDs, tool names, status codes, and latency, but redact bearer tokens, document contents, and personal data.
Troubleshoot common failures
HTTP 403 or authorization failure
- Confirm the token belongs to the identity you intended to deploy, not to a developer account used locally.
- Check that the identity has the required Azure AI Search data role, such as read-only index access where appropriate.
- Verify token audience, claims, expiration, and the exact
Bearerformatting inx-ms-query-source-authorization. - Check whether a Toolbox or proxy is expecting a different authentication mode.
- Retry after role propagation has completed, then test again from the target runtime.
HTTP 400 or 404
- Compare the Search service hostname character by character.
- Confirm the knowledge-base name is the resource name expected by the endpoint, not a display label.
- Confirm the path is
/knowledgebases/<name>/mcp. - Check whether the preview API version is still accepted and update it when Microsoft changes the contract.
- Ensure no reverse proxy or URL builder removed the query parameter.
The model never calls the retrieval tool
- Inspect the result of
get_tools()and confirmknowledge_base_retrievewas discovered. - Check that the model actually supports tool calling and that the discovered tools were passed to
bind_tools. - Strengthen the system instruction requiring retrieval for knowledge-base-dependent questions.
- Verify graph routing includes
tools_conditionand aToolNodeedge back to the model.
The answer is not grounded
- Confirm the tool response is reaching the model as a tool message rather than being discarded by custom state handling.
- Inspect whether the response contains source references and preserve them when transforming messages.
- Test a question whose answer is unambiguously present in one indexed document.
- Review source configuration, indexing freshness, query-planning settings, and document permissions.
Tool discovery works but retrieval errors at runtime
- Check whether the token was valid at discovery time but expired before the user request.
- Inspect request timeouts and retry behavior in the HTTP client.
- Distinguish an empty retrieval result from a transport error and give each a different user-facing response.
- Preserve correlation identifiers so Azure and application logs can be compared.
Production design and security checklist
- Use managed or workload identity where practical, with least-privilege Search data roles.
- Keep endpoint names and API versions in deployment configuration rather than embedding them throughout graph code.
- Rotate secrets and redact authorization headers from traces, exception messages, and LangSmith or application telemetry.
- Set bounded timeouts and deliberate retry policies; do not retry authorization failures indefinitely.
- Limit which graph nodes can invoke the retrieval tool if your application has multiple agents or workflows.
- Make source attribution visible in the response format when users need to verify claims.
- Define behavior for no-result, partial-result, permission-denied, and service-unavailable cases.
- Test document-level access with representative user identities, not only with the deployment administrator.
- Monitor API-version changes because the documented endpoint is a preview contract.
- Keep the model’s general-knowledge fallback explicit so users can distinguish an indexed answer from an ungrounded explanation.
Direct endpoint or Toolbox: a practical decision
Choose the direct endpoint when one LangGraph service owns its Azure identity, can safely manage the authorization header, and does not need a shared MCP control plane. It has fewer moving parts and makes the request path easy to reason about, but each application must implement credential and policy handling correctly.
Choose Toolbox when several clients need the same MCP exposure, when a platform team should control credentials and policy, or when you want to reuse a managed connection across hosted agent and external MCP clients. It introduces another configuration boundary, so document who owns the Toolbox identity, how clients authenticate to it, and how failures are surfaced to LangGraph.
Neither route is demonstrated as universally faster, safer, or cheaper by the component documentation. Base the decision on identity placement, operational ownership, client compatibility, and the degree of centralized configuration you require.
What a successful deployment looks like
A healthy deployment has a current endpoint, a runtime identity authorized to read the configured knowledge sources, successful MCP discovery of knowledge_base_retrieve, and a graph that routes tool calls back to the model. A grounded question produces retrieval output with source references; a question outside the indexed evidence produces an explicit limitation rather than an invented fact. Logs show controlled status and timing information without exposing tokens or document contents.
Azure AI Search remains the system that hosts and retrieves the knowledge base. LangGraph supplies orchestration: it decides when to call the MCP tool, carries the result through graph state, and asks the model to formulate the final response. Keeping those responsibilities separate makes upgrades, permission reviews, and troubleshooting substantially easier.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
