Support optional generic MCP Server knowledge sources in Foundry IQ retrieval

[placerda]

Summary

The current Foundry IQ integration uses an intents-based minimal-reasoning retrieve request and cannot invoke MCP Server knowledge sources. Add opt-in, parameterized support for generic MCP Server knowledge sources so GPT-RAG can retrieve live, tool-backed data from arbitrary MCP servers.

Azure Monitor MCP for natural-language-to-KQL over workspace-based Application Insights is the motivating scenario, but the implementation must remain server-agnostic.

Why will we implement this?

• Problem / opportunity: MCP Server knowledge sources require conversational messages and low or medium reasoning so the knowledge-base planner can select tools and generate arguments. The current client always sends explicit intents with minimal reasoning. Direct retrieve calls also cannot use foundryConnection, and GPT-RAG has no mechanism to forward per-request MCP credentials.
• Business value / outcome: Allow operators to combine existing Foundry IQ sources with live data and capabilities exposed by approved MCP servers without adding server-specific logic to the orchestrator.
• Success metrics (how we know it worked): An operator can enable one or more MCP Server knowledge sources through configuration, authenticate securely, receive normalized results, and keep existing behavior unchanged when the feature is disabled.

What does it do? (Functional Overview)

• Core behavior: Add an optional MCP-aware Foundry IQ retrieval path that uses messages, configurable low or medium reasoning, tool selection, argument generation, runtime limits, and secure credential forwarding.
• Data collection / storage needs: No additional persistent store. Reuse the existing configuration and secret-management patterns.
• Data analysis / reporting needs: Normalize MCP references and structured tool results into the existing retrieval result contract, with useful activity and error telemetry.
• Nice to have (stretch goals): Support multiple MCP servers and per-source tool allowlists in one knowledge base.

Components

• Components (check all that apply):
  • gpt-rag-orchestrator
  • gpt-rag-ingestion
  • gpt-rag-ui
  • gpt-rag-mcp

Current limitations

• FoundryIQClient.retrieve() currently sends hard-coded intents for minimal retrieval. This bypasses the query planning required to inspect MCP tools, select a tool, and generate its arguments.
• MCP Server knowledge sources require messages and low or medium reasoning.
• GPT-RAG invokes the knowledge-base retrieve API directly. In this flow, foundryConnection authentication does not apply.
• The connector does not forward the documented query-time paired headers required for rotating or per-request MCP credentials.
• The deployment and configuration surfaces do not currently support generic MCP Server knowledge sources or their tool allowlists, output parsing, and runtime settings.

Requirements

• The capability must be disabled by default and must not change the existing request body, headers, latency, or results when disabled.
• Support zero, one, or multiple generic MCP Server knowledge sources without MCP-specific code paths.
• Allow operators to configure the knowledge source, server endpoint, approved tools, output parsing, reasoning effort, and maximum runtime.
• Implement a secure authentication mechanism appropriate for direct retrieve calls, including the documented paired query-time headers where required. Do not log credentials or store rotating tokens as static headers.
• Preserve the existing minimal intents path for requests that do not use MCP sources.
• Normalize MCP outputs into the existing citation/reference contract and retain MCP tool activity for troubleshooting.
• Treat the feature as preview while the upstream Azure AI Search MCP Server knowledge-source contract remains preview.

Security

• Use least-privilege identities and explicit tool allowlists.
• Acquire credentials through existing managed identity, workload identity, Key Vault, or OBO patterns as appropriate for the configured MCP server.
• Fail clearly when authentication or MCP configuration is invalid. Do not silently return empty results.
• Bound reasoning runtime and MCP output size.
• Document that MCP tool safety does not guarantee semantic correctness of generated arguments. The reference Azure Monitor scenario must include bounded time ranges, row limits, read-only access, and auditable generated KQL.

Acceptance criteria

• Existing Foundry IQ tests remain unchanged and pass when MCP support is disabled.
• Enabling an MCP source produces a messages request with supported reasoning and runtime settings.
• Configuration supports at least one generic MCP Server knowledge source and an explicit tool allowlist.
• At least one secure credential-forwarding mode works for direct retrieve calls.
• MCP references and structured results are normalized for downstream answer generation and citations.
• Missing credentials, unsupported auth modes, unavailable tools, and timeouts produce actionable errors.
• The implementation is validated end to end with a real MCP server. Azure Monitor MCP querying workspace-based Application Insights should be the reference scenario, not a special code path.

Testing

• Regression tests proving disabled behavior is unchanged.
• Unit tests for MCP source configuration, request shaping, tool allowlists, runtime settings, authentication headers, output normalization, errors, and timeouts.
• Integration tests with a deterministic MCP test server.
• Preview validation against Azure Monitor MCP with representative natural-language questions and generated KQL captured for review.

Documentation

Document configuration, authentication options, latency and cost implications, security guidance, preview status, and a generic MCP example. Include Azure Monitor MCP as a worked example while making clear that the feature supports arbitrary compatible MCP servers.

Non-goals

• Hosting or operating third-party MCP servers for users.
• Azure Monitor-specific behavior in the core connector.
• Enabling MCP knowledge sources by default.
• Guaranteeing semantic correctness of arbitrary tool arguments without server-side validation.

[placerda]

Concluído e publicado de ponta a ponta.

• Release GPT-RAG v3.6.0, promovida pelo PR #570.
• Runtime compatível gpt-rag-orchestrator v3.7.0, implementado no PR #275.
• Provisionamento MCP no PR #568 e documentação no PR #569.
• Guia publicado: Foundry IQ: Generic MCP server knowledge sources.

Validação final: GPT-RAG com 109 testes e 66 subtestes; orchestrator com 457 testes e 65 testes MCP focados; compilação Python, AST/preflight PowerShell, JSON/manifest/tags, contrato canônico, caminho desabilitado, Bicep e limite de tamanho, build estrito da documentação e publicação no Pages aprovados.

A funcionalidade continua em Preview e desabilitada por padrão. O provisionamento v3.6.0 e o orchestrator v3.7.0 devem ser implantados juntos. Não executamos E2E Azure ao vivo porque não havia endpoint MCP e credenciais aprovados; antes de habilitar em produção, ainda é obrigatório executar um canário no endpoint aprovado, com identidade/RBAC, allowlist de ferramentas, limites e consultas geradas revisados.