Edit

Create an MCP Server knowledge source (preview)

Important

These features and functionality are part of the 2026-05-01-preview REST API. The 2026-05-01-preview is licensed to you as part of your Azure subscription and is subject to the terms applicable to "Previews" in the Microsoft Product Terms, the Microsoft Products and Services Data Protection Addendum ("DPA"), and the Supplemental Terms of Use for Microsoft Azure Previews.

The 2026-05-01-preview supports connections to other Microsoft services and third-party services. Use of these services is subject to their respective terms and might result in data processing or storage outside of the Azure compliance boundary, as well as data flowing into the Azure compliance boundary.

It's your responsibility to manage whether your data will flow outside of your organization's compliance and geographic boundaries and any related implications, and that appropriate permissions, boundaries, and approvals are provisioned.

MCP implementations are susceptible to risks, such as attacks, cascading failures, and loss of human oversight. You can mitigate these risks by vetting MCP servers for security and reliability, following Microsoft's recommended practices and industry best practices, and implementing approval mechanisms and monitoring cascading behaviors.

You're responsible for carefully reviewing and testing applications you build in the context of your specific use cases and making all appropriate decisions and customizations. This includes implementing your own responsible AI mitigations, such as metaprompts, content filters, or other safety systems, and ensuring your applications meet appropriate quality, reliability, security, and trustworthiness standards. For more information, see the Azure AI Search Transparency Note.

An MCP Server knowledge source (preview) connects any system that exposes a Model Context Protocol (MCP)–compatible endpoint to an agentic retrieval pipeline in Azure AI Search. Knowledge sources are created independently, referenced in a knowledge base, and used as grounding data when the knowledge base is queried at runtime.

MCP tools surface data and functionality from external systems as callable functions that agents invoke at query time. This makes MCP Server knowledge sources useful when the information you need lives in internal tools, third-party APIs, or custom backends that Azure AI Search doesn't natively support.

Unlike indexed knowledge sources, MCP Server knowledge sources query live data directly at retrieval time. No ingestion pipeline is needed. You provide the MCP server URL and specify which tools Azure AI Search can call at query time.

Usage support

Azure portal Microsoft Foundry portal .NET SDK Python SDK Java SDK JavaScript SDK REST API
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Prerequisites

  • An Azure AI Search service in any region that provides agentic retrieval.

  • An MCP server with one or more tools. The server must be reachable from Azure AI Search over HTTPS. For testing, you can use the public Microsoft Learn MCP server at https://learn.microsoft.com/api/mcp.

  • Permissions to create knowledge sources. Configure keyless authentication with the Search Service Contributor role assigned to your user account (recommended) or use an API key.

Limitations and considerations

  • The minimal retrieval reasoning effort isn't supported. Use low or medium instead.

  • alwaysQuerySource isn't supported on retrieve requests that reference an MCP Server knowledge source.

  • MCP server tool calls involve external network requests and can take longer than typical search queries. Set maxRuntimeInSeconds on retrieve requests to give all configured tools sufficient time to respond.

Check for existing knowledge sources

A knowledge source is a top-level, reusable object. Knowing about existing knowledge sources is helpful for either reuse or naming new objects.

Run the following code to list knowledge sources by name and type.

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

Reference: SearchIndexClient

# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

for ks in index_client.list_knowledge_sources():
    print(f"  - {ks.name} ({ks.kind})")

Reference: SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
api-key: {{api-key}}

Reference: Knowledge Sources - List

You can also return a single knowledge source by name to review its JSON definition.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

Reference: SearchIndexClient

# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))

Reference: SearchIndexClient

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
api-key: {{api-key}}

Reference: Knowledge Sources - Get

The following JSON is an example response for an MCP Server knowledge source.

{
  "name": "my-mcp-server-ks",
  "kind": "mcpServer",
  "description": "An MCP Server knowledge source.",
  "encryptionKey": null,
  "mcpServerParameters": {
    "serverURL": "https://learn.microsoft.com/api/mcp",
    "authentication": null,
    "tools": [
      {
        "name": "microsoft_docs_search",
        "inclusionMode": null,
        "maxOutputTokens": null,
        "outputParsing": {
          "kind": "auto",
          "jsonParameters": null,
          "splitParameters": null
        }
      }
    ]
  }
}

Create a knowledge source

Run the following code to create an MCP Server knowledge source.

using Azure;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

Uri searchEndpoint = new Uri("<search-service-url>");
AzureKeyCredential credential = new AzureKeyCredential("<api-key>");
var indexClient = new SearchIndexClient(searchEndpoint, credential);

var mcpServer = new McpServerKnowledgeSource(
    "<knowledge-source-name>",
    new McpServerKnowledgeSourceParameters(
        "https://learn.microsoft.com/api/mcp",
        new[]
        {
            new McpServerTool
            {
                Name = "microsoft_docs_search",
                OutputParsing = new McpServerAutoOutputParsing(),
                InclusionMode = McpServerToolInclusionMode.Reranked,
                MaxOutputTokens = 1000
            }
        }))
{
    Description = "An MCP Server knowledge source."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(mcpServer);

Reference: SearchIndexClient

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    McpServerKnowledgeSource,
    McpServerParameters,
    McpServerTool,
    McpServerToolOutputParsing,
)

index_client = SearchIndexClient(
    endpoint="<search-service-url>",
    credential=AzureKeyCredential("<api-key>")
)

knowledge_source = McpServerKnowledgeSource(
    name="<knowledge-source-name>",
    description="An MCP Server knowledge source.",
    mcp_server_parameters=McpServerParameters(
        server_url="https://learn.microsoft.com/api/mcp",
        tools=[
            McpServerTool(
                name="microsoft_docs_search",
                output_parsing=McpServerToolOutputParsing(kind="auto"),
                inclusion_mode="reranked",
                max_output_tokens=1000
            )
        ]
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)

Reference: SearchIndexClient

### Create an MCP Server knowledge source
PUT {{search-url}}/knowledgesources/my-mcp-server-ks?api-version=2026-05-01-preview
api-key: {{api-key}}
Content-Type: application/json
Prefer: return=representation

{
  "name": "my-mcp-server-ks",
  "kind": "mcpServer",
  "description": "An MCP Server knowledge source.",
  "encryptionKey": null,
  "mcpServerParameters": {
    "serverURL": "https://learn.microsoft.com/api/mcp",
    "tools": [
      {
        "name": "microsoft_docs_search",
        "outputParsing": {
          "kind": "auto"
        },
        "inclusionMode": "reranked",
        "maxOutputTokens": 1000
      }
    ]
  }
}

Reference: Knowledge Sources - Create or Update

Source-specific properties

The following properties apply to MCP Server knowledge sources.

Name Description Type Editable Required
name The name of the knowledge source, which must be unique within the knowledge sources collection and follow the naming guidelines for objects in Azure AI Search. String No Yes
kind The kind of knowledge source, which is mcpServer in this case. String No Yes
description A description of the knowledge source. String Yes No
encryptionKey A customer-managed key to encrypt sensitive information in the knowledge source. Object Yes No
mcpServerParameters Parameters specific to MCP Server knowledge sources: serverURL, authentication, and tools. Object No Yes
serverURL The URL of the MCP server. String No Yes
authentication Authentication credentials for the MCP server. If omitted, requests are sent without authentication. For supported authentication options, see Authentication options. Object Yes No
tools An array of tools to allow from the MCP server. Must contain at least one entry. Each tool name must be unique within the list and must match a tool exposed by the MCP server. The knowledge source doesn't automatically allow all MCP server tools, so you must explicitly list each tool that is allowed. For supported tool properties, see Tool properties. Array Yes Yes

Authentication options

If your MCP server requires authentication, use one of the following options.

Use foundryConnection only when an agent from Foundry Agent Service invokes a knowledge base that includes this MCP Server knowledge source. In that flow, the service resolves the connection and injects the required credentials when it calls the MCP server. If you call the knowledge base directly or from a client other than Foundry Agent Service, foundryConnection doesn't work.

"authentication": {
  "kind": "foundryConnection",
  "foundryConnectionParameters": {
    "connectionId": "<your-foundry-connection-id>"
  }
}

Pass headers at query time

If an MCP server requires per-request credentials, pass them on the retrieve request using paired control headers. This syntax forwards headers to the MCP server without conflicting with the Authorization or api-key header used to authenticate to Azure AI Search.

Use the knowledge source name as the prefix:

Control header Description
<knowledge-source-name>-header-name<N> The name of the HTTP header to send to the MCP server.
<knowledge-source-name>-header-value<N> The value of the HTTP header to send to the MCP server.

<N> is an optional numeric suffix that pairs multiple headers. For example, my-mcp-server-ks-header-name1 pairs with my-mcp-server-ks-header-value1.

Create the retrieval client with a policy that adds the control headers to the retrieve request.

using Azure;
using Azure.Core;
using Azure.Core.Pipeline;
using Azure.Search.Documents;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

string knowledgeSourceName = "my-mcp-server-ks";

var options = new SearchClientOptions();
options.AddPolicy(new McpPassthroughHeaderPolicy(knowledgeSourceName), HttpPipelinePosition.PerCall);

var retrievalClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri(searchEndpoint),
    knowledgeBaseName: knowledgeBaseName,
    credential: credential,
    options: options);

var request = new KnowledgeBaseRetrievalRequest();
request.Messages.Add(
    new KnowledgeBaseMessage(new[] { new KnowledgeBaseMessageTextContent("Find Azure AI Search MCP guidance.") })
    {
        Role = "user"
    });
request.KnowledgeSourceParams.Add(new SearchIndexKnowledgeSourceParams(knowledgeSourceName));

Response<KnowledgeBaseRetrievalResponse> response = await retrievalClient.RetrieveAsync(request);

sealed class McpPassthroughHeaderPolicy(string knowledgeSourceName) : HttpPipelineSynchronousPolicy
{
    public override void OnSendingRequest(HttpMessage message)
    {
        message.Request.Headers.Add($"{knowledgeSourceName}-header-name", "Authorization");
        message.Request.Headers.Add($"{knowledgeSourceName}-header-value", "Bearer <mcp-server-access-token>");
        message.Request.Headers.Add($"{knowledgeSourceName}-header-name1", "x-custom-auth");
        message.Request.Headers.Add($"{knowledgeSourceName}-header-value1", "<mcp-server-header-value>");
    }
}

Pass the control headers in the headers keyword argument on the retrieve call.

from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
    SearchIndexKnowledgeSourceParams,
)

knowledge_source_name = "my-mcp-server-ks"

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="Find Azure AI Search MCP guidance."
                )
            ],
        )
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(knowledge_source_name=knowledge_source_name)
    ],
)

result = retrieval_client.retrieve(
    request,
    headers={
        f"{knowledge_source_name}-header-name": "Authorization",
        f"{knowledge_source_name}-header-value": "Bearer <mcp-server-access-token>",
        f"{knowledge_source_name}-header-name1": "x-custom-auth",
        f"{knowledge_source_name}-header-value1": "<mcp-server-header-value>",
    },
)

POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-05-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
my-mcp-server-ks-header-name: Authorization
my-mcp-server-ks-header-value: Bearer {{mcp-server-access-token}}
my-mcp-server-ks-header-name1: x-custom-auth
my-mcp-server-ks-header-value1: {{mcp-server-header-value}}

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Find Azure AI Search MCP guidance."
        }
      ]
    }
  ],
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "my-mcp-server-ks",
      "kind": "mcpServer"
    }
  ]
}

Each header pair must include exactly one name control header and one matching value control header. Header names and values must be valid HTTP request headers. If a query-time header uses the same target header name as a storedHeaders entry, the query-time value overrides the stored value for that request.

Tool properties

Each entry in the tools array is an McpServerTool object with the following properties.

Name Description Type Editable Required
name The name of the MCP tool to invoke. Must match a tool name exposed by the MCP server. String No Yes
outputParsing Controls how the tool's raw output is parsed into rankable documents. Defaults to auto. For supported output parsing modes, see Output parsing modes. Object No No
inclusionMode Controls whether the tool's results are included only when ranked highly (reranked) or always regardless of relevance score (always). Defaults to reranked. String Yes No
maxOutputTokens Maximum number of tokens to retain from the tool output before ranking. Defaults to 10,000. Integer No No

Output parsing modes

By default, the retrieval engine applies automatic heuristics (auto) to convert raw MCP tool output into rankable documents. You can override this behavior per tool using the outputParsing property.

The auto mode requires no configuration. The retrieval engine applies heuristics to parse the tool output.

Assign to a knowledge base

If you're satisfied with the knowledge source, add it to a knowledge base.

Query a knowledge base

After the knowledge base is configured, call the retrieve action or MCP endpoint to query MCP server content. MCP Server knowledge sources have source-specific retrieval behavior and response fields.

How retrieval works for MCP Server knowledge sources

At query time, the large language model (LLM) configured in the knowledge base reviews the configured tools, selects which ones to call based on the user query, and generates the arguments for each call. Azure AI Search then invokes the selected tools on the MCP server and returns the results as ranked references.

MCP Server–specific response fields

MCP Server knowledge sources return per-document citations in the references array and per-invocation diagnostics in the activity array. If the knowledge source lists multiple tools and the model selects more than one, a separate activity record appears for each invocation.

The following example shows a retrieve response containing an MCP Server knowledge source reference and its corresponding activity record. For broader guidance on interpreting retrieve responses, see Review the response.

Tip

To receive sourceData for references, set includeReferenceSourceData to true on the knowledge source entry within knowledgeSourceParams on the retrieve request.

{
  "response": [
      // ... Response omitted for brevity
  ],
  "activity": [
    {
      "type": "mcpServer",
      "id": 1,
      "knowledgeSourceName": "my-mcp-server-ks",
      "queryTime": "2026-05-11T15:42:33.0888894Z",
      "count": 10,
      "elapsedMs": 768,
      "mcpServerArguments": {
        "toolName": "microsoft_docs_search",
        "toolArguments": {
          "query": "Azure AI Search features"
        }
      }
    },
    {
      // ... Additional activity records omitted for brevity
    }
  ],
  "references": [
    {
      "type": "mcpServer",
      "id": "0",
      "activitySource": 1,
      "sourceData": {
        "title": "What is a knowledge source?",
        "content": "..."
      },
      "rerankerScore": 2.96,
      "toolName": "microsoft_docs_search",
      "title": "my-mcp-server-ks microsoft_docs_search 1"
    },
    {
      // ... Additional references omitted for brevity
    }
  ]
}

Delete a knowledge source

Before you can delete a knowledge source, you must delete any knowledge base that references it or update the knowledge base definition to remove the reference. For knowledge sources that generate an index and indexer pipeline, all generated objects are also deleted. However, if you used an existing index to create a knowledge source, your index isn't deleted.

If you try to delete a knowledge source that's in use, the action fails and returns a list of affected knowledge bases.

To delete a knowledge source:

  1. Get a list of all knowledge bases on your search service.

    using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeBases = indexClient.GetKnowledgeBasesAsync();

Console.WriteLine("Knowledge Bases:");

await foreach (var kb in knowledgeBases)
{
    Console.WriteLine($"  - {kb.Name}");
}

    Reference: SearchIndexClient

    An example response might look like the following:

     {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

  2. Get an individual knowledge base definition to check for knowledge source references.

    using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge base name to retrieve
string kbNameToGet = "earth-knowledge-base";

// Get a specific knowledge base definition
var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
var kb = knowledgeBaseResponse.Value;

// Serialize to JSON for display
string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

    Reference: SearchIndexClient

    An example response might look like the following:

     {
   "Name": "earth-knowledge-base",
   "KnowledgeSources": [
     {
       "Name": "earth-knowledge-source"
     }
   ],
   "Models": [
     {}
   ],
   "RetrievalReasoningEffort": {},
   "OutputMode": {},
   "ETag": "\u00220x8DE278629D782B3\u0022",
   "EncryptionKey": null,
   "Description": null,
   "RetrievalInstructions": null,
   "AnswerInstructions": null
 }

  3. Either delete the knowledge base or, if you have multiple knowledge sources, update the knowledge base to remove the source. This example shows deletion.

    using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");

    Reference: SearchIndexClient

  4. Delete the knowledge source.

    await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");

    Reference: SearchIndexClient

  1. Get a list of all knowledge bases on your search service.

    # Get knowledge bases
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

print("Knowledge Bases:")
for kb in index_client.list_knowledge_bases():
    print(f"  - {kb.name}")

    Reference: SearchIndexClient

    An example response might look like the following:

     {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

  2. Get an individual knowledge base definition to check for knowledge source references.

    # Get a knowledge base definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
kb = index_client.get_knowledge_base("knowledge_base_name")
print(kb)

    Reference: SearchIndexClient

    An example response might look like the following:

     {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks",
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

  3. Either delete the knowledge base or, if you have multiple knowledge sources, update the knowledge base to remove the source. This example shows deletion.

    # Delete a knowledge base
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_base("knowledge_base_name")
print(f"Knowledge base deleted successfully.")

    Reference: SearchIndexClient

  4. Delete the knowledge source.

    # Delete a knowledge source
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_source("knowledge_source_name")
print(f"Knowledge source deleted successfully.")

    Reference: SearchIndexClient

  1. Get a list of all knowledge bases on your search service.

    ### Get knowledge bases
GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
api-key: {{api-key}}

    Reference: Knowledge Bases - List

    An example response might look like the following:

     {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

  2. Get an individual knowledge base definition to check for knowledge source references.

    ### Get a knowledge base definition
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
api-key: {{api-key}}

    Reference: Knowledge Bases - Get

    An example response might look like the following:

     {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks",
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

  3. Either delete the knowledge base or, if you have multiple knowledge sources, update the knowledge base to remove the source. This example shows deletion.

    ### Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
api-key: {{api-key}}

    Reference: Knowledge Bases - Delete

  4. Delete the knowledge source.

    ### Delete a knowledge source
DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
api-key: {{api-key}}

    Reference: Knowledge Sources - Delete

Related content

  • Last updated on