Criar uma fonte de conhecimento do Servidor MCP (pré-visualização)

• O pacote de pré-visualização mais recente Azure.Search.Documents: dotnet add package Azure.Search.Documents --prerelease

• O pacote de pré-visualização mais recente azure-search-documents: pip install --pre azure-search-documents

• A versão 2026-05-01-preview das APIs REST do Serviço de Pesquisa.

// 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}");
}

Referência: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})")

Referência:SearchIndexClient

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

Referência:Fontes de Conhecimento - Lista

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));

Referência: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))

Referência:SearchIndexClient

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

Referência:Fontes de Conhecimento - Obter

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);

Referência: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)

Referência: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
      }
    ]
  }
}

Referência:Fontes de Conhecimento - Criar ou Atualizar

Crie o cliente de recuperação com uma política que adicione os cabeçalhos de controlo ao pedido de recuperação.

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>");
    }
}

Passe os cabeçalhos de controlo no argumento nomeado headers na chamada a retrieve.

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"
    }
  ]
}

1. Obtenha uma lista de todas as bases de conhecimento do seu serviço de pesquisa.

   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}");
   }
   

   Referência:SearchIndexClient

   Um exemplo de resposta pode ter a seguinte aparência:

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

2. Obtenha uma definição individual da base de conhecimento para verificar referências de fontes de conhecimento.

   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);
   

   Referência:SearchIndexClient

   Um exemplo de resposta pode ter a seguinte aparência:

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

3. Ou apagas a base de conhecimento ou, se tiveres várias fontes de conhecimento, atualizas a base de conhecimento para remover a fonte. Este exemplo mostra a exclusão.

   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.");
   

   Referência:SearchIndexClient

4. Exclua a fonte de conhecimento.

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

   Referência:SearchIndexClient

1. Obtenha uma lista de todas as bases de conhecimento do seu serviço de pesquisa.

   # 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}")
   

   Referência:SearchIndexClient

   Um exemplo de resposta pode ter a seguinte aparência:

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

2. Obtenha uma definição individual da base de conhecimento para verificar referências de fontes de conhecimento.

   # 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)
   

   Referência:SearchIndexClient

   Um exemplo de resposta pode ter a seguinte aparência:

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

3. Ou apagas a base de conhecimento ou, se tiveres várias fontes de conhecimento, atualizas a base de conhecimento para remover a fonte. Este exemplo mostra a exclusão.

   # 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.")
   

   Referência:SearchIndexClient

4. Exclua a fonte de conhecimento.

   # 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.")
   

   Referência:SearchIndexClient

1. Obtenha uma lista de todas as bases de conhecimento do seu serviço de pesquisa.

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

   Referência:Bases de Conhecimento - Lista

   Um exemplo de resposta pode ter a seguinte aparência:

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

2. Obtenha uma definição individual da base de conhecimento para verificar referências de fontes de conhecimento.

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

   Referência:Bases de Conhecimento - Obter

   Um exemplo de resposta pode ter a seguinte aparência:

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

3. Ou apagas a base de conhecimento ou, se tiveres várias fontes de conhecimento, atualizas a base de conhecimento para remover a fonte. Este exemplo mostra a exclusão.

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

   Referência:Bases de Conhecimento - Eliminar

4. Exclua a fonte de conhecimento.

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

   Referência:Fontes de Conhecimento - Eliminar