fabric-rti-mcp

🎯 Overview

A comprehensive Model Context Protocol (MCP) server implementation for Microsoft Fabric Real-Time Intelligence (RTI).

This server enables AI agents to interact with Fabric RTI services by providing tools through the MCP interface, allowing for seamless data querying, analysis, and streaming capabilities.

> [!NOTE]

> This project is in Public Preview and implementation may significantly change prior to General Availability.

🔍 How It Works

The Fabric RTI MCP Server acts as a bridge between AI agents and Microsoft Fabric RTI services:

• 🔄 MCP Protocol: Uses the Model Context Protocol to expose Fabric RTI capabilities as tools
• 🏗️ Natural Language to KQL: AI agents can translate natural language requests into KQL queries and Eventstream management
• 💡 Secure Authentication: Leverages Azure Identity for seamless, secure access to your resources
• ⚡ Real-time Data Access: Direct connection to Eventhouse and Eventstreams for live data analysis
• 📊 Unified Interface: For both analytics and streaming workloads with intelligent parameter suggestions

✨ Supported Services

Eventhouse (Kusto): Execute KQL queries against Microsoft Fabric RTI Eventhouse and Azure Data Explorer (ADX).

Eventstreams: Manage Microsoft Fabric Eventstreams for real-time data processing:

• List Eventstreams in workspaces
• Get Eventstream details and definitions
• Create new Eventstreams
• Update existing Eventstreams
• Delete Eventstreams

Activator: Create and manage Microsoft Fabric Activator triggers for real-time alerting:

• Create new triggers with KQL source monitoring
• Set up email and Teams notifications when a condition occurs
• List Activator artifacts in workspaces

Map: Create and manage Microsoft Fabric Map to visualize geospatial data:

• Create a new map from a provided configuration
• Visualize data on maps
• List Map items in workspaces
• Delete Map items

🧠 Copilot Skills

This repository includes a KQL Copilot Skill (`.github/skills/kql/`) that gives AI agents deep KQL expertise when writing, debugging, or reviewing Kusto queries. The skill covers:

• Syntax gotchas and self-correction patterns for common KQL errors
• Dynamic type discipline, join patterns, datetime pitfalls
• Memory-safe query patterns and result-size discipline
• Advanced functions: graph queries, vector similarity, geospatial operations, time series
• Query templates for deduplication, top-N, sessionization, pivoting, and more
• Full error-to-fix mapping for rapid recovery

The skill references the Fabric RTI MCP tools (`kusto_query`, `kusto_command`, `kusto_sample_entity`, etc.) so agents know how to execute queries through this MCP server.

🚧 Coming soon

• Other RTI items

🔍 Example Prompts

Eventhouse Analytics:

• "Get databases in my Eventhouse"
• "Sample 10 rows from table 'StormEvents' in Eventhouse"
• "What can you tell me about StormEvents data?"
• "Analyze the StormEvents to come up with trend analysis across past 10 years of data"
• "Analyze the commands in 'CommandExecution' table and categorize them as low/medium/high risks"
• "Before running this query, check the execution plan and tell me if it's expensive"
• "Compare these two query approaches and tell me which is more efficient"
• "Check the cluster health — do we have enough capacity for a heavy analytics job?"

Eventstream Management:

• "List all Eventstreams in my workspace"
• "Show me the details of my IoT data Eventstream"
• "Create a new Eventstream for processing sensor data"
• "Update my existing Eventstream to add a new destination"

Activator Alerts:

• "Using the StormEvents table, notify me via email when there is a flood in Illinois"
• "Create a teams alert to notify me when my success rate drops below 95%"
• "List all Activator artifacts in my workspace"

Map Visualization:

• "List all Map items in my workspace"
• "Create a new Map and add LakeHouse with name 'MyLakeHouse' as a data source to Map item 'MyMap'"
• "Delete a Map item with name 'MyMap' from my workspace"

Available tools

Eventhouse (Kusto) - 13 Tools + 1 Optional:

• `kusto_known_services` - List all available Kusto services configured in the MCP
• `kusto_query` - Execute KQL queries on the specified database
• `kusto_command` - Execute Kusto management commands (`.show`, `.create`, `.alter`, `.drop`)
• `kusto_list_entities` - List entities (databases, tables, external tables, materialized views, functions, graphs) in a cluster or database
• `kusto_describe_database` - Get schema information for all entities in a database
• `kusto_describe_database_entity` - Get detailed schema for a specific entity (table, external table, materialized view, function, graph)
• `kusto_graph_query` - Execute graph queries using snapshots or transient graphs
• `kusto_sample_entity` - Retrieve sample records from a table, external table, materialized view, or function
• `kusto_ingest_inline_into_table` - Ingest inline CSV data into a specified table
• `kusto_get_shots` *(when `KUSTO_SHOTS_TABLE` is configured)* - Find semantically similar saved KQL queries using local SLM or Azure OpenAI embeddings
• `kusto_deeplink_from_query` - Generate a deeplink URL to open a KQL query in Azure Data Explorer Web Explorer or Microsoft Fabric query workbench
• `kusto_show_queryplan` - Retrieve the execution plan for a KQL query without running it. Returns planning stats (PlanSize, RelopSize), the logical operator tree, and execution hints (estimated row counts, concurrency/spread hints, per-shard scan info with filter detection). Useful for comparing query approaches, catching expensive joins, and validating query syntax before execution.
• `kusto_diagnostics` - Run a best-effort suite of cluster diagnostic commands and return a unified summary. Sections: capacity (resource slots), cluster (nodes/hardware), principal roles (caller permissions), internal diagnostics (health/utilization), workload groups, rowstores, and ingestion failures (last 24h). Each section runs independently — permission failures on one section don't block others.

Eventstreams - 17 Tools:

Core Operations (6 tools):

• `eventstream_list` - List all Eventstreams in your Fabric workspace
• `eventstream_get` - Get detailed information about a specific Eventstream
• `eventstream_get_definition` - Retrieve complete JSON definition of an Eventstream
• `eventstream_create` - Create new Eventstreams with custom configuration (auto-includes default stream)
• `eventstream_update` - Modify existing Eventstream settings and destinations
• `eventstream_delete` - Remove Eventstreams and associated resources

Builder Tools (11 tools):

• Session Management: `eventstream_start_definition`, `eventstream_get_current_definition`, `eventstream_clear_definition`
• Sources: `eventstream_add_sample_data_source`, `eventstream_add_custom_endpoint_source`
• Streams: `eventstream_add_derived_stream`
• Destinations: `eventstream_add_eventhouse_destination`, `eventstream_add_custom_endpoint_destination`
• Validation: `eventstream_validate_definition`, `eventstream_create_from_definition`, `eventstream_list_available_components`

> 💡 Pro Tip: All tools work with natural language! Just describe what you want to do and the AI agent will use the appropriate tools automatically.

Activator - 2 Tools:

• `activator_list_artifacts` - List all Activator artifacts in a Fabric workspace
• `activator_create_trigger` - Create new Activator triggers with KQL source monitoring and email/Teams alerts

Map - 7 Tools:

• `map_list` - List all Map items in your Fabric workspace
• `map_get` - Get detailed information about a specific Map item
• `map_get_definition` - Retrieve the full JSON definition of a Map item
• `map_create` - Create a new Map item from a provided configuration
• `map_update_definition` - Replace the full JSON definition of an existing Map item
• `map_update` - Partially update properties of an existing Map item
• `map_delete` - Delete a Map item and its associated configuration

Getting Started

Prerequisites

1. Install either the stable or Insiders release of VS Code:

2. Install the GitHub Copilot and GitHub Copilot Chat extensions

3. Install `uv`

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

or, check here for other install options

4. Open VS Code in an empty folder

Install from PyPI (Pip)

The Fabric RTI MCP Server is available on PyPI, so you can install it using pip. This is the easiest way to install the server.

From VS Code

1. Open the command palette (Ctrl+Shift+P) and run the command `MCP: Add Server`

2. Select install from Pip

3. When prompted, enter the package name `microsoft-fabric-rti-mcp`

4. Follow the prompts to install the package and add it to your settings.json or your mcp.json file

The process should end with the below settings in your `settings.json` or your `mcp.json` file.

settings.json

{
    "mcp": {
        "servers": {
            "fabric-rti-mcp": {
                "command": "uvx",
                "args": [
                    "microsoft-fabric-rti-mcp"
                ],
                "env": {
                    "KUSTO_SERVICE_URI": "https://help.kusto.windows.net/",
                    "KUSTO_SERVICE_DEFAULT_DB": "Samples",
                    "FABRIC_API_BASE": "https://api.fabric.microsoft.com/v1"
                }
            }
        }
    }
}

> Note: All environment variables are optional. The `KUSTO_SERVICE_URI` and `KUSTO_SERVICE_DEFAULT_DB` provide default cluster and database settings. `AZ_OPENAI_EMBEDDING_ENDPOINT` configures the default AOAI embedding method used by `kusto_get_shots`.

From GitHub Copilot CLI

Use the interactive command within a GitHub Copilot CLI session:

/mcp add

Or manually add to your `~/.copilot/mcp-config.json`:

{
    "mcpServers": {
        "fabric-rti-mcp": {
            "command": "uvx",
            "args": [
                "microsoft-fabric-rti-mcp"
            ],
            "env": {
                "KUSTO_SERVICE_URI": "https://help.kusto.windows.net/",
                "KUSTO_SERVICE_DEFAULT_DB": "Samples",
                "FABRIC_API_BASE": "https://api.fabric.microsoft.com/v1"
            }
        }
    }
}

For more information, see the GitHub Copilot CLI documentation.

🔧 Manual Install (Install from source)

1. Make sure you have Python 3.10+ installed properly and added to your PATH.

2. Clone the repository

3. Install the dependencies (`pip install .` or `uv tool install .`)

4. Add the settings below into your vscode `settings.json` or your `mcp.json` file.

5. Modify the path to match the repo location on your machine.

6. Modify the cluster uri in the settings to match your cluster.

7. Modify the cluster default database in the settings to match your database.

8. Modify the embeddings endpoint in the settings to match yours. This step is optional and needed only in case you supply a shots table

{
    "mcp": {
        "servers": {
            "fabric-rti-mcp": {
                "command": "uv",
                "args": [
                    "--directory",
                    "C:/path/to/fabric-rti-mcp/",
                    "run",
                    "-m",
                    "fabric_rti_mcp.server"
                ],
                "env": {
                    "KUSTO_SERVICE_URI": "https://help.kusto.windows.net/",
                    "KUSTO_SERVICE_DEFAULT_DB": "Samples",
                    "FABRIC_API_BASE": "https://api.fabric.microsoft.com/v1"
                }
            }
        }
    }
}

🐛 Debugging the MCP Server locally

Assuming you have python installed and the repo cloned:

Install locally

pip install -e ".[dev]"

Configure

Follow the Manual Install instructions.

Attach the debugger

Start the MCP server normally from the client that will invoke its tools, then set a breakpoint on an executable

line. If you changed the Python source after the server started, restart the MCP server before attaching.

Option 1: Attach by process ID

Press F5 and select `Python Debugger: Attach by Process ID`. VS Code needs the PID of the Python process that is

running `-m fabric_rti_mcp.server`. You can identify it in either of these ways:

1. VS Code process picker: Select the matching Python process from the list. If several related processes are

shown, select the deepest Python child running `-m fabric_rti_mcp.server`, not the `uv` wrapper.

2. Manual PID lookup: If VS Code asks you to enter a PID instead of displaying the process list, find it with

Task Manager or PowerShell:

`python.exe` process.

$servers = @(Get-CimInstance Win32_Process | Where-Object {
         $_.Name -eq "python.exe" -and
         $_.CommandLine -match "-m\s+fabric_rti_mcp\.server"
     })

     $servers |
         Where-Object { $_.ProcessId -notin $servers.ParentProcessId } |
         Sort-Object CreationDate -Descending |
         Select-Object -First 1 ProcessId, CommandLine

Enter the returned `ProcessId` in the VS Code prompt.

On newer Windows versions, `wmic.exe` is disabled or removed. Some Python debugger versions still use it to

populate the process picker, causing process enumeration to fail. The manual methods above do not require WMIC.

Option 2: Inject debugpy and attach on port 5678

This repository includes the `Python Debugger: Attach to Fabric RTI MCP` launch configuration and its

`Inject debugger into Fabric RTI MCP` pre-launch task. This Windows-specific option uses PowerShell to find the

deepest Fabric RTI MCP Python process, inject `debugpy`, and connect VS Code to `127.0.0.1:5678`.

1. Ensure the MCP server is already running.

2. Press F5 and select `Python Debugger: Attach to Fabric RTI MCP`.

3. Wait for the VS Code debug toolbar to appear.

4. Invoke the target tool from the same MCP client session that started the attached server.

Do not add `debugpy --listen` to the MCP server command. Some clients may start or reconnect to the command more

than once, which can cause port collisions. If multiple MCP client sessions are running, close the unrelated

sessions first so the debugger attaches to the intended server process.

🧪 Test the MCP Server

Via GitHub Copilot

1. Open GitHub Copilot in VS Code and switch to Agent mode

2. You should see the Fabric RTI MCP Server in the list of tools

3. Try prompts that tell the agent to use the RTI tools, such as:

4. The agent should be able to use the Fabric RTI MCP Server tools to complete your query

⚙️ Configuration

The MCP server can be configured using the following environment variables:

Required Environment Variables

None - the server will work with default settings for demo purposes.

Optional Environment Variables

`FABRIC_RTI_ALLOWED_TOOLS` accepts service names derived from the registered `*_tools` modules and full tool names.

Shots Embedding Configuration

All supported AOAI and SLM embedding paths return L2-normalized vectors. `kusto_get_shots` uses their known unit

magnitudes when calculating cosine similarity to avoid recalculating vector magnitudes for every shot. Custom or

manually generated `EmbeddingVector` values must therefore also be L2-normalized.

SLM embeddings

`kusto_get_shots` defaults to Azure OpenAI embeddings for backward compatibility. To use local SLM embeddings,

set `embedding_method` to `slm` for an individual call, or set `KUSTO_SHOTS_EMBEDDING_METHOD=slm` for the MCP

server. Configure the server's default model with `KUSTO_SHOTS_SLM_MODEL`; it defaults to

`harrier-v1-270m`. Explicit tool arguments override these server defaults. The queried database must contain a

pre-deployed `slm_embeddings_fl` function. Follow the SLM embeddings function documentation

and select either Azure Data Explorer or Microsoft Fabric from the Version selector in the left pane

for the correct deployment instructions.

The documented `slm_embeddings_fl` implementation supports:

Example SLM arguments:

{
  "prompt": "Find a few storm events in Texas",
  "cluster_uri": "https://mycluster.westus.kusto.windows.net",
  "database": "MyDatabase",
  "shots_table_name": "Shots",
  "embedding_method": "slm",
  "slm_model_name": "harrier-v1-270m"
}

The SLM prompt is embedded with the `query:` prefix. The table's `EmbeddingVector` values must use the same model and vector dimension; for retrieval models, embed the stored `EmbeddingText` corpus with the corresponding `passage:` convention.

The MCP tool does not deploy the function or migrate existing shot vectors.

Azure OpenAI embeddings

AOAI is the default embedding method. Follow the AI embeddings plugin documentation and select either Azure Data Explorer or Microsoft Fabric from the Version selector in the left pane for the applicable setup instructions.

Example AOAI arguments:

{
  "prompt": "Find a few storm events in Texas",
  "cluster_uri": "https://mycluster.westus.kusto.windows.net",
  "database": "MyDatabase",
  "shots_table_name": "Shots",
  "embedding_method": "aoai",
  "embedding_endpoint": "https://your-resource.openai.azure.com/openai/deployments/text-embedding-ada-002/embeddings?api-version=2024-10-21;impersonate"
}

If `embedding_endpoint` isn't supplied, AOAI calls use `AZ_OPENAI_EMBEDDING_ENDPOINT`.

Format Requirements:

https://{your-openai-resource}.openai.azure.com/openai/deployments/{deployment-name}/embeddings?api-version={api-version};impersonate

Components:

• `{your-openai-resource}`: Your Azure OpenAI resource name
• `{deployment-name}`: Your text embedding deployment name (e.g., `text-embedding-ada-002`)
• `{api-version}`: API version (e.g., `2024-10-21`, `2023-05-15`)
• `;impersonate`: Authentication method (you might use managed identity)

Authentication Requirements:

• Your Azure identity must have access to the OpenAI resource
• In case of using managed identity, the OpenAI resource must be configured to accept managed identity authentication
• The deployment must exist and be accessible

Configuration of Shots Table

The `kusto_get_shots` tool retrieves shots that are most similar to your prompt from the shots table. This function requires configuration of:

• Shots table: Should have an "EmbeddingText" (string) column containing the natural language prompt, "AugmentedText" (string) column containing the respective KQL, and "EmbeddingVector" (dynamic) column containing the embedding vector of the EmbeddingText.
• Matching embeddings: The prompt and `EmbeddingVector` column must use the same provider, model, vector dimension, and compatible query/corpus conventions.

Existing AOAI calls remain backward compatible. When `embedding_method="slm"` is selected, `embedding_endpoint` is ignored.

🔑 Authentication

In `stdio` mode (local), the MCP Server integrates with your host operating system's authentication mechanisms.

We use Azure Identity via `DefaultAzureCredential`, which tries these authentication methods in order:

1. Environment Variables (`EnvironmentCredential`) - Perfect for CI/CD pipelines

2. Visual Studio (`VisualStudioCredential`) - Uses your Visual Studio credentials

3. Azure CLI (`AzureCliCredential`) - Uses your existing Azure CLI login

4. Azure PowerShell (`AzurePowerShellCredential`) - Uses your Az PowerShell login

5. Azure Developer CLI (`AzureDeveloperCliCredential`) - Uses your azd login

6. Interactive Browser (`InteractiveBrowserCredential`) - Falls back to browser-based login if needed

If you're already logged in through any of these methods, the Fabric RTI MCP Server will automatically use those credentials in `stdio` mode.

This MCP server is not intended to be exposed directly as a production HTTP endpoint.

If you choose to run it over HTTP, the deployment must provide its own security boundary before requests reach this server.

For example, put any Entra-aware authentication layer in front of it.

The HTTP configuration options below are guardrails and local-development conveniences; they are not a substitute for a production authentication boundary.

By default, HTTP requests must provide an `Authorization` bearer token; the server performs deployment-agnostic bearer token shape screening and forwards the bearer to downstream Fabric/Kusto services, or exchanges it with OBO when OBO is enabled.

It does not perform cryptographic Entra JWT signature, issuer, tenant, or audience validation.

HTTP Mode Configuration for MCP Server

When the MCP server is running locally to the agent in HTTP mode or is deployed to Azure, the following environment variables are used to define and enable HTTP mode. You can find practical examples of this setup in the `tests/live/test_kusto_tools_live_http.py` file:

HTTP credential behavior:

Binding HTTP to a non-loopback address such as `0.0.0.0` exposes the MCP listener outside the local process boundary.

Non-loopback HTTP without an explicit host allow-list is allowed only in `FABRIC_RTI_HTTP_DEBUG_MODE`.

This exception is for local testing only; it does not make direct HTTP exposure production-safe.

HTTP clients connecting to the server need to include the appropriate authentication token in the request headers unless `FABRIC_RTI_HTTP_ALLOW_MI` or `FABRIC_RTI_HTTP_DEBUG_MODE` is explicitly enabled:

# Example from test_kusto_tools_live_http.py
auth_header = f"Bearer {token.token}"

headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "Authorization": auth_header,
}

OBO Flow Authentication

If your scenario involves a user token with a non-Kusto audience and you need to exchange it for a Kusto audience token using the OBO flow, the Fabric RTI MCP Server can handle this exchange automatically by setting the following environment variables:

This flow is typically used in OAuth scenarios where a gateway like Azure API Management (APIM) is involved (example: https://github.com/ai-microsoft/adsmcp-apim-dual-validation?tab=readme-ov-file). The user authenticates via Entra ID, and APIM forwards the token to the MCP server. The token audience is not Kusto, so the MCP server must perform an OBO token exchange to get a token with the Kusto audience.

To support this setup, your Microsoft Entra App must be configured to use Federated Credentials following the official guide: https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation. This enables the app to exchange tokens (OBO).

Additionally, the Entra app must be granted Azure Data Explorer API permissions to successfully acquire an OBO token with the Kusto audience.

Remote Deployment

The MCP server can be deployed using the method of your choice. For example, you can follow the guide at https://github.com/Azure-Samples/mcp-sdk-functions-hosting-python/blob/main/ExistingServer.md to deploy the MCP server to an Azure Function App.

🛡️ Security Note

Your credentials are always handled securely through the official Azure Identity SDK - we never store or manage tokens directly.

MCP as a phenomenon is very novel and cutting-edge. As with all new technology standards, consider doing a security review to ensure any systems that integrate with MCP servers follow all regulations and standards your system is expected to adhere to. This includes not only the Azure MCP Server, but any MCP client/agent that you choose to implement down to the model provider.

You should follow Microsoft security guidance for MCP servers, including enabling Entra ID authentication, secure token management, and network isolation. Refer to Microsoft Security Documentation for details.

👥 Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a

Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us

the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide

a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions

provided by the bot. You will only need to do this once across all repos using our CLA.

Permissions and Risk

MCP clients can invoke operations based on the user’s Fabric Role-Based Access Control (RBAC) permissions. Autonomous or misconfigured clients may perform destructive actions. You should review and apply least-privilege RBAC roles and implement safeguards before deployment. Certain safeguards, such as flags to prevent destructive operations, are not standardized in the MCP specification and may not be supported by all clients. 

Compliance Responsibility

This MCP server may be installed, used and share data with clients and services, such as third party LLMs, AI agents or services that operate outside Fabric’s compliance boundaries. You are responsible for ensuring that any integration complies with applicable organizational, regulatory, and contractual requirements.

Third Party Components

This MCP server may use or depend on third party components.  You are responsible for reviewing and complying with the licenses and security posture of any third-party components.

Export Control

Use of this software must comply with all applicable export laws and regulations, including U.S. Export Administration Regulations and local jurisdiction requirements.

No Warranty / Limitation of Liability

This software is provided “as is” without warranties or conditions of any kind, either express or implied. Microsoft shall not be liable for any damages arising from use, misuse, or misconfiguration of this software.

🤝 Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct.

For more information see the Code of Conduct FAQ or

contact opencode@microsoft.com with any additional questions or comments.

📚 Documentation

• **Changelog** - Release history and breaking changes
• **Contributing** - Contribution guidelines

Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft

trademarks or logos is subject to and must follow

Microsoft's Trademark & Brand Guidelines.

Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.

Any use of third-party trademarks or logos are subject to those third-party's policies.