Live Knowledge Sources for Azure AI Search

Query-time MCP and Fabric Ontology grounding for Foundry IQ:
see which live source answered, which tool ran, and which references came back.

Read the execution manual for the GitHub Pages-ready runbook: choose a path, run commands, inspect success signals, and follow the official Microsoft Learn links.

One Knowledge Base can route a query to live MCP tools and governed Fabric semantics, then return the trace contract: activity, references, and sourceData.

🎬 See it in action — a ~5 min walkthrough from git clone to a verified deployment (clone → local mock → test → deploy → verify → cleanup), with real footage of the demo app and an executed notebook (offline / dry-run — no secrets on screen).

⬇ Download the full video: English (5 min) · 한국어 (5분)  ·  chapters & how to rebuild

What This Is

• MCP Server Knowledge Source calls allowed tools on a remote HTTPS MCP server during Knowledge Base retrieval.
• Fabric Ontology Knowledge Source grounds answers in governed Fabric semantics with delegated source authorization.
• One Knowledge Base can route across both sources and return inspectable activity, references, and sourceData.

This is a reusable sample accelerator, not a production reference architecture. It uses Azure AI Search public preview Knowledge Source APIs (2026-05-01-preview). Keep the official Learn manuals as the source of truth while preview behavior evolves.

Why This Repo

• See the trace, not just the docs. Offline responses show the actual retrieve contract: which source ran, which tool was called, and what evidence came back.
• Run it in 30 seconds with zero setup. Learn the contract without Azure keys, tenant access, or a Fabric workspace.
• Go live with one command. Move from offline replay to mcp-only, byo-fabric, or full deployment paths when you are ready.

This repo complements the official Learn manuals by packaging runnable payloads, notebooks, deployment scripts, and offline evidence around the same preview APIs.

What You'll Learn

1. Inspect offline retrieve traces with no cloud setup.
2. Walk through MCP Server KS and Fabric Ontology KS in notebooks.
3. Deploy a live demo app and verify the same trace contract against your tenant.

Try It In 30 Seconds

No Azure subscription, keys, tenant, or Fabric workspace required:

python3 samples/python/inspect_retrieve_response.py samples/responses/mcp-retrieve.sample.json

You should see Activity, References, and Source Data Preview sections.

Try the combined offline trace:

python3 samples/python/inspect_retrieve_response.py samples/responses/combined-airline-ops-retrieve.sample.json

It shows Fabric Ontology activity for Airline Ops business data and MCP Server activity for Microsoft Learn implementation guidance.

For a lightweight first checkout, use a shallow clone:

git clone --depth 1 https://github.com/microsoft/azure-ai-search-foundry-iq-live-knowledge-sources.git

Walkthrough videos are hosted on GitHub Releases instead of git. Keep large recordings, generated app builds, deployment reports, and dependency folders out of source control so forks and fresh clones stay small.

Deploy A Live Demo

Choose the path that matches your tenant state.

Before deploying, install azd, az, python3, node, and npm, then sign in. See deployment prerequisites.

The default app is Azure Static Web Apps plus a managed Functions API. Browser code never receives Search admin keys or Azure OpenAI keys.

Safety defaults: the deploy wrapper validates templates, payloads, and the app before provisioning; failed deployments print cleanup commands; generated Fabric IDs are saved for teardown; and destroy.sh continues to azd down --purge --force even if Fabric cleanup needs manual follow-up.

The app is one way to view the same trace contract. It reveals the response in stages so you can explain query, answer, source activity, references, and source data during a demo. For a longer presenter flow, see Demo Walkthrough.

How It Works

The Knowledge Base composes the live sources. Each retrieve call can hint which sources to use through knowledgeSourceParams, then the response exposes activity, references, and sourceData.

Every path follows the same loop:

Create Knowledge Source
  -> attach it to a Knowledge Base
    -> retrieve with a test question
      -> inspect activity, references, and sourceData

The sample uses a synthetic Airline Operations domain with fictional carrier names and real airport geography. It is safe for public demos while still showing realistic semantic joins and trace behavior.

What Gets Created

Generated deployment logs and reports stay under ignored paths such as .deployment/ and deployments/.

Learn More

Primary Manuals

• Create an MCP Server knowledge source
• Create a Fabric Ontology knowledge source
• Create a knowledge base
• Query a knowledge base

Repository Map

docs/                 Concept, deployment, troubleshooting, and FAQ
infra/                Bicep for Azure AI Search, Azure OpenAI, Storage, and app hosting
scripts/              Deploy, destroy, E2E, Fabric, validation, and postprovision helpers
static-app/           Canonical demo app for Azure Static Web Apps + Functions
samples/rest/         Raw REST request sequence
samples/python/       Small helper scripts for payload generation and trace inspection
samples/responses/    Offline retrieve responses
samples/data/         Synthetic Airline Ops data
samples/ontology/     Airline Ops ontology contract
notebooks/            Guided MCP and Fabric tutorials
src/ks_factory/       Reusable Python payload builders
assets/               Diagrams and demo screenshots

Local Validation

Run this before opening a PR or sharing the sample broadly:

bash scripts/validate-local.sh

The gate checks shell syntax, Python compile, Python contract tests, notebook JSON, Markdown links, sample hygiene, repository size hygiene, payload generation, offline responses, no-secret scan, Static Web Apps build, and Bicep build when Azure CLI is available.

To check repository weight before a PR, run:

python3 scripts/check-repo-size.py

For agent-readable preflight, run:

python3 tools/doctor.py --format json
python3 tools/validate.py --profile offline --format json

Security Notes

• Do not commit tenant IDs, service URLs, API keys, bearer tokens, raw live responses, generated deployment reports, or local screenshots with sensitive values.
• MCP Server KS requires a remote HTTPS MCP server. Local stdio MCP servers cannot be attached directly.
• Fabric live retrieve requires a raw end-user Search access token in x-ms-query-source-authorization; do not prefix it with Bearer.
• Offline replay is for learning trace shape. It is not proof of live Fabric retrieval.

Contributing

Issues and PRs are welcome. Please read CONTRIBUTING.md, SECURITY.md, and SUPPORT.md.

This project is licensed under the MIT License.