@microsoft/fabric-mcp-darwin-arm64 1.4.0 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +536 -42
- package/dist/fabmcp +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,71 +1,77 @@
|
|
|
1
1
|
# <img height="36" width="36" src="https://learn.microsoft.com/fabric/media/fabric-icon.png" alt="Microsoft Fabric Logo" /> Microsoft Fabric MCP Server NPM Package
|
|
2
2
|
|
|
3
3
|
|
|
4
|
-
A local-first Model Context Protocol (MCP) server that provides AI agents with comprehensive access to Microsoft Fabric's public APIs, item definitions, and best practices.
|
|
4
|
+
A local-first Model Context Protocol (MCP) server that provides AI agents with comprehensive access to Microsoft Fabric's public APIs, item definitions, and best practices. Documentation tools use bundled specifications without connecting to live Fabric environments; operational tools call Fabric APIs using the configured identity.
|
|
5
5
|
## Table of Contents
|
|
6
6
|
- [Overview](#overview)
|
|
7
7
|
- [Installation](#installation)
|
|
8
|
-
|
|
9
|
-
- [VS Code (Recommended)](#vs-code-recommended)
|
|
10
|
-
- [Manual Setup](#manual-setup)
|
|
8
|
+
- [Docker](#docker)
|
|
11
9
|
- [Usage](#usage)
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- [
|
|
21
|
-
- [
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
10
|
+
- [Getting Started](#getting-started)
|
|
11
|
+
- [What can you do with the Fabric MCP Server?](#what-can-you-do-with-the-fabric-mcp-server)
|
|
12
|
+
- [Capacity Discovery](#capacity-discovery)
|
|
13
|
+
- [Catalog Discovery](#catalog-discovery)
|
|
14
|
+
- [Fabric Item Types & APIs](#fabric-item-types--apis)
|
|
15
|
+
- [Resource Definitions & Schemas](#resource-definitions--schemas)
|
|
16
|
+
- [Best Practices & Examples](#best-practices--examples)
|
|
17
|
+
- [Development Workflows](#development-workflows)
|
|
18
|
+
- [Workspace Metadata](#workspace-metadata)
|
|
19
|
+
- [Available Tools](#available-tools)
|
|
20
|
+
- [API Documentation & Best Practices](#api-documentation--best-practices)
|
|
21
|
+
- [OneLake Data Operations](#onelake-data-operations)
|
|
22
|
+
- [OneLake Security — Data Access Roles](#onelake-security--data-access-roles)
|
|
23
|
+
- [OneLake Shortcuts](#onelake-shortcuts)
|
|
24
|
+
- [OneLake Settings](#onelake-settings)
|
|
25
|
+
- [Core Fabric Operations](#core-fabric-operations)
|
|
26
|
+
- [Data Factory Operations](#data-factory-operations)
|
|
27
27
|
- [Support and Reference](#support-and-reference)
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
28
|
+
- [Documentation](#documentation)
|
|
29
|
+
- [Feedback and Support](#feedback-and-support)
|
|
30
|
+
- [Security](#security)
|
|
31
|
+
- [Data Collection](#data-collection)
|
|
32
|
+
- [Contributing](#contributing)
|
|
33
|
+
- [Code of Conduct](#code-of-conduct)
|
|
34
34
|
- [License](#license)
|
|
35
35
|
|
|
36
36
|
# Overview
|
|
37
37
|
|
|
38
|
-
**Microsoft Fabric MCP Server** gives your AI agents the knowledge they need to generate robust, production-ready code for Microsoft Fabric
|
|
38
|
+
**Microsoft Fabric MCP Server** gives your AI agents the knowledge they need to generate robust, production-ready code for Microsoft Fabric, alongside authenticated tools for working with Fabric resources.
|
|
39
39
|
|
|
40
40
|
Key capabilities:
|
|
41
41
|
- **Complete API Context**: Full OpenAPI specifications for all supported Fabric item types
|
|
42
42
|
- **Item Definition Knowledge**: JSON schemas for every Fabric item type (Lakehouses, pipelines, semantic models, notebooks, etc.)
|
|
43
43
|
- **Built-in Best Practices**: Embedded guidance on pagination, error handling, and recommended patterns
|
|
44
|
-
- **Local-First
|
|
44
|
+
- **Local-First Documentation**: Documentation tools read bundled resources locally; operational tools access Fabric under the configured identity
|
|
45
|
+
- **Workspace Metadata Updates**: Rename a known workspace or update or clear its description without changing other properties
|
|
45
46
|
- **Data Factory Integration**: Pipeline and Dataflow Gen2 management with M query execution
|
|
46
47
|
|
|
47
48
|
# Installation
|
|
48
|
-
|
|
49
|
-
|
|
49
|
+
|
|
50
|
+
The manual configuration examples use `mcpServers` as the root object. In Visual Studio and Visual Studio Code, use `servers` instead.
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
When using the VS Code extension, `fabricMcp.enabledServices` selects from `core`, `docs`, `onelake`, and `datafactory`. Leave the list empty to enable all toolsets. If an existing setting contains `publicapis`, replace it with `docs` or clear the list; saved settings are not migrated automatically.
|
|
54
|
+
|
|
55
|
+
- Install a supported Node.js LTS version **22.0.0 or later**, with `npm` and `npx` available on your system `PATH`. Verify your installation with `node --version`, `npm --version`, and `npx --version`.
|
|
56
|
+
- Configure the `mcp.json` file with the following:
|
|
50
57
|
|
|
51
58
|
```json
|
|
52
59
|
{
|
|
53
60
|
"mcpServers": {
|
|
54
61
|
"fabric-mcp-server": {
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
62
|
+
"command": "npx",
|
|
63
|
+
"args": [
|
|
64
|
+
"-y",
|
|
65
|
+
"@microsoft/fabric-mcp@latest",
|
|
66
|
+
"server",
|
|
67
|
+
"start",
|
|
68
|
+
"--mode",
|
|
69
|
+
"all"
|
|
63
70
|
]
|
|
64
71
|
}
|
|
65
72
|
}
|
|
66
73
|
}
|
|
67
74
|
```
|
|
68
|
-
**Note:** When manually configuring Visual Studio and Visual Studio Code, use `servers` instead of `mcpServers` as the root object.
|
|
69
75
|
|
|
70
76
|
**Client-Specific Configuration**
|
|
71
77
|
| IDE | File Location | Documentation Link |
|
|
@@ -76,6 +82,45 @@ Key capabilities:
|
|
|
76
82
|
| **VS Code** | `.vscode/mcp.json` (workspace)<br>`settings.json` (user) | [VS Code MCP Documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) |
|
|
77
83
|
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | [Windsurf Cascade MCP Integration](https://docs.windsurf.com/windsurf/cascade/mcp) |
|
|
78
84
|
|
|
85
|
+
## Docker
|
|
86
|
+
|
|
87
|
+
The published container image is available from [Microsoft Container Registry](https://mcr.microsoft.com/artifact/mar/fabric/fabric-mcp) as `mcr.microsoft.com/fabric/fabric-mcp`. Use Docker with Linux containers. The `latest` tag selects the most recently published image; when pinning a version, choose a tag that already exists in the registry.
|
|
88
|
+
|
|
89
|
+
The container does **not** inherit your host's `az login` session. For operational tools, configure an identity supported by the Fabric APIs you intend to call and grant it the required Fabric permissions. For example, supply a service principal using a local environment file stored outside your repository:
|
|
90
|
+
|
|
91
|
+
```text
|
|
92
|
+
AZURE_TENANT_ID=<tenant-id>
|
|
93
|
+
AZURE_CLIENT_ID=<client-id>
|
|
94
|
+
AZURE_CLIENT_SECRET=<client-secret>
|
|
95
|
+
AZURE_TOKEN_CREDENTIALS=EnvironmentCredential
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Never commit this file or put its secret values in `mcp.json`. See [environment credential options](https://learn.microsoft.com/dotnet/api/azure.identity.environmentcredential) for other supported credential settings.
|
|
99
|
+
|
|
100
|
+
Configure your MCP client, replacing the environment-file placeholder with an absolute path:
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"mcpServers": {
|
|
105
|
+
"fabric-mcp-server": {
|
|
106
|
+
"command": "docker",
|
|
107
|
+
"args": [
|
|
108
|
+
"run",
|
|
109
|
+
"--rm",
|
|
110
|
+
"-i",
|
|
111
|
+
"--env-file",
|
|
112
|
+
"<absolute-path-to-env-file>",
|
|
113
|
+
"mcr.microsoft.com/fabric/fabric-mcp:latest",
|
|
114
|
+
"--mode",
|
|
115
|
+
"all"
|
|
116
|
+
]
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Keep stdin open with `-i`, without allocating a TTY. The image entrypoint already runs `server start`; do not repeat those arguments after the image name.
|
|
123
|
+
|
|
79
124
|
# Usage
|
|
80
125
|
|
|
81
126
|
## Getting Started
|
|
@@ -93,12 +138,27 @@ Key capabilities:
|
|
|
93
138
|
|
|
94
139
|
The Fabric MCP Server supercharges your agents with Microsoft Fabric context. Here are some prompts you can try:
|
|
95
140
|
|
|
141
|
+
### Capacity Discovery
|
|
142
|
+
|
|
143
|
+
* "List Fabric capacities where I am an administrator or contributor"
|
|
144
|
+
* "Show the IDs, SKUs, regions, and states of my accessible Fabric capacities"
|
|
145
|
+
* "Get the next page of Fabric capacities using the continuation token from the previous response"
|
|
146
|
+
|
|
147
|
+
`core_list-capacities` returns exactly one page of capacity metadata in `capacities`, with `continuationToken` and `continuationUri` when supplied by Fabric. Pass the token unchanged through `--continuation-token` to request another page. Returned URIs are metadata only and are never followed; the tool does not retrieve all pages automatically.
|
|
148
|
+
|
|
149
|
+
The [Fabric List Capacities API](https://learn.microsoft.com/rest/api/fabric/core/capacities/list-capacities) lists capacities where the calling principal is an administrator or contributor. It supports users, service principals, and managed identities. Delegated calls require `Capacity.Read.All` or `Capacity.ReadWrite.All`; this is not an Azure subscription inventory and takes no subscription parameter.
|
|
150
|
+
|
|
96
151
|
### Catalog Discovery
|
|
97
152
|
|
|
98
153
|
* "Search the OneLake catalog for items related to 'sales revenue'"
|
|
99
154
|
* "Find a Lakehouse with 'customer' in the name across my workspaces"
|
|
100
155
|
* "Discover all Report items in the catalog and show which workspace they live in"
|
|
101
156
|
* "Filter the catalog to Warehouse and Notebook items"
|
|
157
|
+
* "List the Fabric workspaces I can access and show their capacity and domain metadata"
|
|
158
|
+
* "List my Fabric workspaces where I am an Admin or Member"
|
|
159
|
+
* "List accessible Fabric workspaces and include their workspace-specific API endpoints"
|
|
160
|
+
* "List item metadata in my Fabric workspace, including nested folders"
|
|
161
|
+
* "Show only the Lakehouses directly in this Fabric folder"
|
|
102
162
|
|
|
103
163
|
### Fabric Item Types & APIs
|
|
104
164
|
|
|
@@ -125,14 +185,46 @@ The Fabric MCP Server supercharges your agents with Microsoft Fabric context. He
|
|
|
125
185
|
|
|
126
186
|
### Development Workflows
|
|
127
187
|
|
|
188
|
+
* "Get the metadata for Fabric item '<item-id>' in workspace '<workspace-id>' without reading its data or definition"
|
|
189
|
+
* "Show the display name, description, and type of Fabric item '<item-id>' in workspace '<workspace-id>'"
|
|
128
190
|
* "Generate a data pipeline configuration with sample data sources"
|
|
129
191
|
* "Help me scaffold a Fabric workspace with Lakehouse and notebooks"
|
|
192
|
+
* "Create a Microsoft Fabric workspace called Sales Planning"
|
|
193
|
+
* "Create a Fabric workspace called Capacity Analytics using the existing capacity with ID \<capacity-id>"
|
|
130
194
|
* "Show me how to handle long-running operations in Fabric APIs"
|
|
131
195
|
* "What's the recommended error handling pattern for Fabric API calls?"
|
|
132
196
|
|
|
197
|
+
## Workspace Metadata
|
|
198
|
+
|
|
199
|
+
Use `core_get-workspace` to retrieve metadata for one known workspace through the [Get Workspace REST API](https://learn.microsoft.com/rest/api/fabric/core/workspaces/get-workspace).
|
|
200
|
+
|
|
201
|
+
* "Get metadata for Fabric workspace `aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa`."
|
|
202
|
+
* "Show the capacity, domain, and workspace identity for Fabric workspace `aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa`."
|
|
203
|
+
* "Get Fabric workspace `aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa` with workspace-specific API and OneLake endpoints."
|
|
204
|
+
|
|
205
|
+
| Argument | Required | Description |
|
|
206
|
+
|----------|----------|-------------|
|
|
207
|
+
| `workspace-id` | Yes | Nonempty workspace UUID, not a name or URL. Accepted UUID representations are normalized before the request. |
|
|
208
|
+
| `prefer-workspace-specific-endpoints` | No | Boolean endpoint preference. Omit to preserve the service default, or explicitly pass `true` or `false`. |
|
|
209
|
+
|
|
210
|
+
```powershell
|
|
211
|
+
fabmcp core get-workspace --workspace-id aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa
|
|
212
|
+
fabmcp core get-workspace --workspace-id aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa --prefer-workspace-specific-endpoints true
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
The result contains a `workspace` object with `id` and `displayName`. When returned by Fabric it also includes `type`, `description`, `capacityId`, `capacityAssignmentProgress`, `capacityRegion`, `domainId`, `workspaceIdentity`, `oneLakeEndpoints`, `apiEndpoint`, and applied `tags`. Missing/null optional fields are omitted; an explicitly empty tag list remains empty. New workspace types, capacity regions, and progress values are preserved.
|
|
216
|
+
|
|
217
|
+
Workspace identity fields contain application and service-principal IDs, not credentials. Returned endpoints are metadata only: this tool never contacts them. Workspaces with public access disabled may return workspace-specific OneLake endpoints even when the preference is omitted or false; an absent API endpoint is not inferred.
|
|
218
|
+
|
|
219
|
+
The tool does not list workspaces or items, read item data or definitions, modify resources, or poll capacity assignments. Errors retain their HTTP status without exposing backend bodies. A 429 includes validated `Retry-After` guidance when available, but the tool does not automatically retry.
|
|
220
|
+
|
|
221
|
+
**Permissions:** The caller needs Viewer-or-higher workspace access. Delegated callers also need `Workspace.Read.All` or `Workspace.ReadWrite.All`. The API supports users, service principals, and managed identities subject to their permissions and Fabric configuration. The tool preserves the server's configured credentials: stdio/hosting identity uses the host's credential provider, and HTTP/OBO uses the current caller's delegated context.
|
|
222
|
+
|
|
223
|
+
By default, the MCP text response contains the command envelope with `results.workspace`. With `--structured-output-mode compact` or `--structured-output-mode duplicated`, the server also advertises the typed output schema and returns `structuredContent.workspace`.
|
|
224
|
+
|
|
133
225
|
## Available Tools
|
|
134
226
|
|
|
135
|
-
The Fabric MCP Server exposes
|
|
227
|
+
The Fabric MCP Server exposes four toolsets: `core`, `docs`, `onelake`, and `datafactory`.
|
|
136
228
|
|
|
137
229
|
### API Documentation & Best Practices
|
|
138
230
|
|
|
@@ -200,10 +292,404 @@ The Fabric MCP Server exposes tools organized into three categories:
|
|
|
200
292
|
|
|
201
293
|
### Core Fabric Operations
|
|
202
294
|
|
|
295
|
+
The configured Fabric Core HTTP client does not automatically follow redirects. This policy applies to all Core operations, including existing create/search and update calls as well as deletion: a returned 3xx response is surfaced as a failure instead of following its Location. Existing configured handlers, proxy settings, timeouts, credentials, and recording wrappers are retained. Workspace `type` is optional in Get, List, Create, and Update responses; omitted/null values are not invented, while present nonempty future type strings are preserved.
|
|
296
|
+
|
|
203
297
|
| Tool Name | Description |
|
|
204
298
|
|-----------|-------------|
|
|
205
|
-
| `
|
|
206
|
-
| `core_create-item` | Creates
|
|
299
|
+
| `core_assign-workspace-to-capacity` | Submits one request to assign an existing workspace to a capacity. Returns an accepted/pending receipt, not confirmation of completion. |
|
|
300
|
+
| `core_create-item` | Creates a Fabric item by workspace UUID. Returns completed metadata or an accepted operation receipt; optionally waits within a bounded budget. |
|
|
301
|
+
| `core_create-workspace` | Creates a Fabric workspace, optionally assigning an existing capacity and domain in the same request. |
|
|
302
|
+
| `core_delete-item` | Deletes one known Fabric item using workspace and item UUIDs. Permanent deletion requires explicitly setting `hard-delete` to `true`. |
|
|
303
|
+
| `core_delete-workspace` | Deletes one explicitly identified Fabric workspace **and the items under it**. Requires a workspace UUID and workspace Admin access. |
|
|
304
|
+
| `core_get-capacity` | Gets one Fabric capacity's ID, display name, SKU, region, and state using its capacity UUID. |
|
|
305
|
+
| `core_get-item` | Gets generic metadata for one existing Fabric item using its workspace ID and item ID. Does not read item data or definitions. |
|
|
306
|
+
| `core_get-operation-result` | Reads one completed operation's JSON or empty result, up to 1 MiB. Binary results are unsupported. |
|
|
307
|
+
| `core_get-operation-state` | Reads one operation's current state and polling guidance, without polling or resubmitting the original request. |
|
|
308
|
+
| `core_get-workspace` | Gets one workspace's metadata by UUID, including optional capacity, domain, identity, tags, and endpoints. Does not read item data or modify resources. |
|
|
309
|
+
| `core_list-capacities` | Lists one page of accessible Fabric capacity metadata: ID, display name, SKU, region, and state, plus available continuation information. |
|
|
310
|
+
| `core_list-items` | Lists one page of Fabric Core item metadata in a known workspace or folder, with optional type filtering and continuation information. |
|
|
311
|
+
| `core_list-workspaces` | Lists one page of accessible workspace management metadata, optionally filtered by the caller's workspace roles. Returns continuation information and can request workspace-specific API endpoints. |
|
|
312
|
+
| `core_search-catalog` | Searches one page of OneLake catalog metadata across workspaces. Continue with the returned token without repeating search or filter. |
|
|
313
|
+
| `core_update-item` | Updates an existing item's display name or description and returns metadata only. |
|
|
314
|
+
| `core_update-workspace` | Renames a workspace or updates or clears its description by UUID, leaving omitted properties unchanged. Requires workspace Admin access. |
|
|
315
|
+
|
|
316
|
+
**Create Item (`core_create-item`)**
|
|
317
|
+
|
|
318
|
+
Calls the [Create Item API](https://learn.microsoft.com/rest/api/fabric/core/items/create-item) once with `display-name`, `item-type`, and optional `description`. Supply a nonempty workspace UUID using `workspace-id` or the backward-compatible `workspace` alias. Workspace names are not resolved. A `workspace-id` that is not empty or whitespace takes precedence when both options are supplied, even if it is invalid; the command does not silently fall back to the alias. Invalid and all-zero UUIDs are rejected before authentication or HTTP, and accepted UUID formats are normalized in the request URL.
|
|
319
|
+
|
|
320
|
+
Missing required options are identified by their registered names, such as `--display-name` or `--item-type`, before any service call. Other parser failures return sanitized guidance without echoing supplied values or unknown option names.
|
|
321
|
+
|
|
322
|
+
This example **creates a real item** when run with authorized credentials:
|
|
323
|
+
|
|
324
|
+
```powershell
|
|
325
|
+
fabmcp core create-item --workspace-id cfafbeb1-8037-4d0c-896e-a46fb27ff229 --display-name "Sales" --item-type Lakehouse
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
The caller needs **Contributor or higher workspace access**. Delegated calls require `Item.ReadWrite.All` or the item-specific `ReadWrite.All` scope. Non-Power BI items require a supported Fabric capacity and [tenant/capacity settings that enable Fabric item creation](https://learn.microsoft.com/fabric/admin/fabric-switch); Power BI items require the appropriate license. Service-principal and managed-identity support depends on the item type. Item types remain strings rather than a fixed client-side list.
|
|
329
|
+
|
|
330
|
+
Display names must follow the item's naming rules, and descriptions allow at most 256 characters. The tool does not supply item definitions, creation payloads, folders, or sensitivity-label settings. Item types that require a definition or creation payload need a different creation path.
|
|
331
|
+
|
|
332
|
+
Create Item supports both outcomes documented by its endpoint: **201** returns validated metadata in the existing `results.item` shape; **202** returns an explicit `results.operation` receipt, never an empty/default item. Both modes return a synchronous 201 result immediately, without operation reads or requiring an operation ID. Other success codes, including 200 and 204, are not part of this endpoint's contract: they produce a sanitized unconfirmed-outcome error with guidance to check whether creation occurred. The shared LRO infrastructure also supports synchronous 200 for future adapters whose endpoints document it; it does not accept arbitrary success codes.
|
|
333
|
+
|
|
334
|
+
| Optional argument | Default | Behavior |
|
|
335
|
+
|-------------------|---------|----------|
|
|
336
|
+
| `sync` | `false` | False sends one POST and returns completed metadata or an accepted receipt, with zero follow-up reads. True asynchronously waits after 202 and retrieves the created item when available. It does not use blocking HTTP I/O. |
|
|
337
|
+
| `max-wait-seconds` | `120` | Finite positive local wait budget after 202, up to **600 seconds (10 minutes)** inclusive. Fractional seconds are allowed. Includes delays, authentication, and in-flight status/result reads. Larger values are rejected, not clamped, before submitting creation, even when `sync=false`. |
|
|
338
|
+
| `early-poll` | `true` | Allows one first status probe after at most 3 seconds, or sooner if the initial server hint is shorter. False honors the initial validated `Retry-After` instead. |
|
|
339
|
+
|
|
340
|
+
Choose the mode **before the single creation request**. This is an alternative to the earlier creation example, not a way to resume an already accepted creation:
|
|
341
|
+
|
|
342
|
+
```powershell
|
|
343
|
+
fabmcp core create-item --workspace-id cfafbeb1-8037-4d0c-896e-a46fb27ff229 --display-name "Sales" --item-type Lakehouse --sync true --max-wait-seconds 120 --early-poll false
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
The early first probe is a deliberate exception to the **initial successful 202** `Retry-After` guidance (often 20 seconds); it is not a claim that every server hint is honored. The receipt keeps `serverRetryAfterSeconds` separate from `recommendedPollAfterSeconds`. After that first probe, subsequent polls honor validated returned hints. Only safe operation GETs can be retried on HTTP 429/503, within the remaining budget; those hints are never shortened by the early-probe exception. Missing, malformed, multiple, negative, or overflowing hints use a conservative 20-second fallback. Valid HTTP-date hints are supported; zero/past hints have a one-second scheduling floor to prevent a tight loop.
|
|
347
|
+
|
|
348
|
+
The 600-second maximum is a server-enforced operational guard on **MCP waiting**, not a Fabric API requirement or a limit on how long the Fabric operation may run. The shared service validation enforces it even when invoked without the command binding layer.
|
|
349
|
+
|
|
350
|
+
Creation is **never automatically resubmitted**. Stopping MCP waiting does not cancel Fabric's operation, and no detached job continues polling. Client cancellation or a shorter HTTP/client timeout can end the wait sooner than the configured budget. A local budget expiry is not a failed mutation: resume using the operation ID, rather than increasing the budget by issuing another create call.
|
|
351
|
+
|
|
352
|
+
| Outcome | Command status and payload |
|
|
353
|
+
|---------|----------------------------|
|
|
354
|
+
| Immediate 201 completion | HTTP 200 command response with `results.item`, preserving the existing completed shape. |
|
|
355
|
+
| Accepted or wait budget expired while unconfirmed | HTTP 202 with `operation.status` `Accepted` or `Pending`; `lastState` is included only after a state read. Acceptance does not invent `Running`. |
|
|
356
|
+
| Accepted without a usable `x-ms-operation-id` | HTTP 202 with `AcceptedWithoutOperationId` and an explicit issue. Check whether creation occurred; do not automatically resubmit. `Location` is not used to recover a missing ID. |
|
|
357
|
+
| Wait observes `Succeeded` and retrieves valid item metadata | HTTP 200 with `item` and a `Succeeded` operation receipt. |
|
|
358
|
+
| Wait observes `Failed` | HTTP 502 with a `Failed` receipt and safe operation error details. No result fetch or new POST is attempted. |
|
|
359
|
+
| A state read fails | A sanitized error with a `TrackingStopped` receipt, preserving the ID and last-known state; this is not evidence that Fabric's operation failed. |
|
|
360
|
+
| Operation succeeded but the result was not retrieved | `ResultUnavailable`, preserving `lastState.status=Succeeded` when observed. Budget expiry returns HTTP 202; read/validation failures retain their error status. Do not recreate the item. |
|
|
361
|
+
| Caller cancels a post-acceptance wait | HTTP 408 with a receipt when the client can still receive it, distinguishing caller cancellation from budget expiry. Confirmed completion is not downgraded to running. |
|
|
362
|
+
|
|
363
|
+
Failures suppress raw backend messages, exception details, stack traces, and local paths. HTTP 403 can indicate permissions or unavailable tenant/capacity features; status-less network failures retain HTTP 503. Before acceptance is known, a timeout, cancellation, network failure, or invalid response can leave the mutation outcome uncertain; check whether creation occurred before retrying.
|
|
364
|
+
|
|
365
|
+
**Long-running operation tools**
|
|
366
|
+
|
|
367
|
+
The [Get Operation State](https://learn.microsoft.com/rest/api/fabric/core/long-running-operations/get-operation-state) and [Get Operation Result](https://learn.microsoft.com/rest/api/fabric/core/long-running-operations/get-operation-result) tools each take only `operation-id`, a nonempty UUID. Each invocation performs **one GET**, with no implicit polling, retries, mutation, or cancellation. URLs are constructed from the fixed Fabric API base and the validated ID. Returned links are not followed or returned as action URLs, and a response cannot replace the requested operation ID.
|
|
368
|
+
|
|
369
|
+
An agent-driven flow starts with the receipt from the original `sync=false` creation:
|
|
370
|
+
|
|
371
|
+
```json
|
|
372
|
+
{
|
|
373
|
+
"operation": {
|
|
374
|
+
"status": "Accepted",
|
|
375
|
+
"operationId": "0acd697c-1550-43cd-b998-91bfbfbd47c6",
|
|
376
|
+
"serverRetryAfterSeconds": 20,
|
|
377
|
+
"recommendedPollAfterSeconds": 3
|
|
378
|
+
}
|
|
379
|
+
}
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
Wait for the recommendation, then make one state read. If still pending, wait for that response's guidance before the next read. After `Succeeded`, fetch the result for Create Item, which is a result-bearing API:
|
|
383
|
+
|
|
384
|
+
```powershell
|
|
385
|
+
fabmcp core get-operation-state --operation-id 0acd697c-1550-43cd-b998-91bfbfbd47c6
|
|
386
|
+
# Only after the state says Succeeded:
|
|
387
|
+
fabmcp core get-operation-result --operation-id 0acd697c-1550-43cd-b998-91bfbfbd47c6
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
A state GET returning HTTP 200 means the **read** succeeded, not necessarily the mutation. The returned `state.status` can be `Undefined`, `NotStarted`, `Running`, `Succeeded`, `Failed`, or a future string. Unknown states are preserved and handled conservatively, never interpreted as successful completion. Progress (0-100) and timestamps are optional. Failed states expose only a safe error code and request UUID, not backend error text or nested details.
|
|
391
|
+
|
|
392
|
+
The generic result is not assumed to be a Fabric item. It uses `{ "operationId": "...", "hasBody": true, "value": ... }` for JSON objects, arrays, or scalars. JSON `null` remains `hasBody=true, value=null`; an actually empty HTTP 200 body uses `hasBody=false` with `value` omitted. Nonempty bodies require `application/json`. **Binary (`application/octet-stream`) and other media are explicitly unsupported, even if empty.** JSON responses are limited to **1 MiB (1,048,576 bytes)**, including streamed responses without `Content-Length`; oversized or malformed content produces a sanitized error, never truncation or fabricated success.
|
|
393
|
+
|
|
394
|
+
As described in the [Fabric LRO guidance](https://learn.microsoft.com/rest/api/fabric/articles/long-running-operation), not every operation has a result. For an API explicitly documented as having no result, confirmed `Succeeded` is sufficient; do not fetch `/result`. Neither HTTP 404 nor an absent `Location` proves successful no-result completion. The shared dispatcher/poller supports explicit result-bearing and no-result adapters; **workspace capacity assignment retains its existing submit-only contract** and is not retrofitted with sync waiting in this release.
|
|
395
|
+
|
|
396
|
+
Both read tools require the **same resource permissions and delegated scopes as the initiating API**. Read-only discovery is not an authorization grant. Credential resolution remains per call, including every poll and result read, with the configured caller's identity.
|
|
397
|
+
|
|
398
|
+
**Catalog Search (`core_search-catalog`)**
|
|
399
|
+
|
|
400
|
+
Calls the [Catalog Search API](https://learn.microsoft.com/rest/api/fabric/core/catalog/search) for one page of metadata visible to the caller. Delegated calls require `Catalog.Read.All`; catalog discovery does not grant access to item contents.
|
|
401
|
+
|
|
402
|
+
```powershell
|
|
403
|
+
# Initial page.
|
|
404
|
+
fabmcp core search-catalog --search "Sales" --filter "Type eq 'Report'" --page-size 25
|
|
405
|
+
|
|
406
|
+
# Next page: copy the token unchanged; do not repeat search or filter.
|
|
407
|
+
fabmcp core search-catalog --continuation-token '<token from the preceding page>'
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
A continuation token already carries the original search, filter, and page size. Combining `continuation-token` with `search` or `filter` is rejected locally with HTTP 400 before service, authentication, or network calls; supplied criteria are never silently dropped. `page-size` remains optional and must be between 1 and 1000 when supplied, including with a token.
|
|
411
|
+
|
|
412
|
+
Success keeps the existing nested command envelope: entries are in `results.results.value`, and the next token is in `results.results.continuationToken`. Entries retain their typed metadata and available `hierarchy.workspace` information. There is no all-pages fetch, polling, or automatic retry. HTTP failures retain their original status with sanitized messages, while status-less network failures retain HTTP 503; raw exception details are not included in public error results.
|
|
413
|
+
|
|
414
|
+
**Get Item (`core_get-item`)**
|
|
415
|
+
|
|
416
|
+
Calls the [Get Item API](https://learn.microsoft.com/rest/api/fabric/core/items/get-item) once.
|
|
417
|
+
Both `workspace-id` and `item-id` are required nonempty UUIDs, normalized before authentication or HTTP.
|
|
418
|
+
The result contains an `item` object with `id`, `displayName`, `type`, `workspaceId`, and `description`
|
|
419
|
+
when available. Missing/null descriptions are omitted and an explicitly empty description is preserved.
|
|
420
|
+
The returned item and workspace IDs must match the requested IDs. Unlike workspace metadata, item
|
|
421
|
+
`type` is required; future nonempty type strings are accepted.
|
|
422
|
+
|
|
423
|
+
```powershell
|
|
424
|
+
fabmcp core get-item --workspace-id <workspace-id> --item-id <item-id>
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
The caller needs read permission for the item. Delegated callers also need `Item.Read.All`,
|
|
428
|
+
`Item.ReadWrite.All`, or an appropriate item-specific read scope. Authentication uses the host's
|
|
429
|
+
configured credential provider and preserves the caller's context; the tool does not grant permissions.
|
|
430
|
+
|
|
431
|
+
This read-only tool does not resolve names, retrieve definitions or data, return workload-specific
|
|
432
|
+
properties, or request default-identity information. Use `core_search-catalog` to discover an unknown
|
|
433
|
+
item ID. Only the documented HTTP 200 metadata response is accepted.
|
|
434
|
+
|
|
435
|
+
For MCP clients, `--structured-output-mode compact` or `--structured-output-mode duplicated` exposes
|
|
436
|
+
the typed output schema and `structuredContent.item`. The default mode keeps content-only responses
|
|
437
|
+
with `results.item`.
|
|
438
|
+
|
|
439
|
+
Command validation uses the shared sanitized handling; service errors do not expose raw backend
|
|
440
|
+
bodies. HTTP 429 includes a valid `Retry-After` delay in seconds or retry time in UTC when supplied.
|
|
441
|
+
Missing, malformed, negative, out-of-range, or multiple headers produce generic retry guidance.
|
|
442
|
+
The tool does not retry automatically or follow redirects.
|
|
443
|
+
|
|
444
|
+
**Get Capacity (`core_get-capacity`)**
|
|
445
|
+
|
|
446
|
+
Calls [Get Capacity](https://learn.microsoft.com/rest/api/fabric/core/capacities/get-capacity):
|
|
447
|
+
`GET https://api.fabric.microsoft.com/v1/capacities/{capacityId}`.
|
|
448
|
+
The required `capacity-id` argument (`--capacity-id` in the CLI) must be a nonempty UUID, not a capacity name or Azure resource ID. Invalid IDs are rejected before authentication or network access.
|
|
449
|
+
|
|
450
|
+
```powershell
|
|
451
|
+
fabmcp core get-capacity --capacity-id 96f3f0ff-4fe2-4712-b61b-05a456ba9357
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
The typed result contains only capacity metadata:
|
|
455
|
+
|
|
456
|
+
```json
|
|
457
|
+
{
|
|
458
|
+
"capacity": {
|
|
459
|
+
"id": "96f3f0ff-4fe2-4712-b61b-05a456ba9357",
|
|
460
|
+
"displayName": "F4 Capacity",
|
|
461
|
+
"sku": "F4",
|
|
462
|
+
"region": "West Central US",
|
|
463
|
+
"state": "Active"
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
All five fields are required. SKU, region, and state remain strings so new service values are preserved. The tool does not list capacities, access ARM or billing, read item data, change capacity settings, assign workspaces, or start or poll long-running operations.
|
|
469
|
+
|
|
470
|
+
The caller needs **Administrator or Contributor** permission on the capacity. Delegated access requires **Capacity.Read.All** or **Capacity.ReadWrite.All**. The API documents support for users, service principals, and managed identities; this tool uses the server's configured credential without changing authentication behavior.
|
|
471
|
+
|
|
472
|
+
Failures preserve the service status with sanitized messages. For throttling, valid `Retry-After` guidance is returned without automatic retries. The operation expects a synchronous HTTP 200 response and rejects incomplete or invalid metadata instead of returning an empty success.
|
|
473
|
+
|
|
474
|
+
Example prompts: "Get metadata for Fabric capacity 96f3f0ff-4fe2-4712-b61b-05a456ba9357" or "Show the SKU, region, and state of Fabric capacity 96f3f0ff-4fe2-4712-b61b-05a456ba9357."
|
|
475
|
+
|
|
476
|
+
**Listing workspace management metadata**
|
|
477
|
+
|
|
478
|
+
`core_list-workspaces` calls the [Core List Workspaces REST API](https://learn.microsoft.com/rest/api/fabric/core/workspaces/list-workspaces). Use it to discover workspace IDs and inspect management metadata. Unlike `onelake_list-workspaces`, it does not use the OneLake storage/data-plane listing. Unlike `core_search-catalog`, it enumerates workspaces rather than searching catalog items. It does not read item data or definitions, modify resources, or perform long-running operations.
|
|
479
|
+
|
|
480
|
+
| Optional parameter | Behavior |
|
|
481
|
+
|---|---|
|
|
482
|
+
| `--roles` | Comma-separated Admin, Member, Contributor, or Viewer roles for the calling principal. Case and surrounding whitespace are normalized; duplicate roles are removed. Unknown roles and empty entries are rejected. Omit for no role filter. |
|
|
483
|
+
| `--continuation-token` | Token returned by the preceding page. Pass it unchanged, including any percent escapes, and repeat the same roles and endpoint preference. Omit for the first page. Empty or whitespace-only tokens are rejected. |
|
|
484
|
+
| `--prefer-workspace-specific-endpoints` | Set `true` to request each workspace's `apiEndpoint` metadata, or `false` to exclude it. Omission preserves the API default. Returned endpoints are not contacted by this tool. |
|
|
485
|
+
|
|
486
|
+
```powershell
|
|
487
|
+
fabmcp core list-workspaces
|
|
488
|
+
fabmcp core list-workspaces --roles Admin,Member --prefer-workspace-specific-endpoints true
|
|
489
|
+
fabmcp core list-workspaces --roles Admin,Member --prefer-workspace-specific-endpoints true --continuation-token '<token from the preceding page>'
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
Each call returns **one server-sized page** in `results.workspaces`, plus `results.continuationToken` and `results.continuationUri` when supplied by Fabric. Structured MCP output uses the same payload without the command envelope. An empty workspace array can still have continuation information; no continuation information means enumeration is complete. There is no page-size option or automatic all-pages fetch. `continuationUri` is informational only and is never followed.
|
|
493
|
+
|
|
494
|
+
Workspace entries contain `id`, `displayName`, and `type`, with `description`, `capacityId`, `capacityRegion`, `domainId`, `tags` (ID and display name), and `apiEndpoint` when available. Missing optional metadata is omitted rather than guessed or fetched separately; explicit empty descriptions and tag arrays are preserved. The role filter does not add a role field to the response. Requesting endpoint metadata does not configure private-link connectivity or change the listing endpoint.
|
|
495
|
+
|
|
496
|
+
The API supports users, service principals, and managed identities. Delegated access requires `Workspace.Read.All` or `Workspace.ReadWrite.All`; service principals and managed identities also require the Fabric tenant setting permitting service principals to use Fabric APIs. Results are limited to workspaces accessible to the configured calling identity, including the authenticated caller when using HTTP/OBO. The tool does not change authentication configuration.
|
|
497
|
+
|
|
498
|
+
Failures preserve the service's HTTP status without exposing raw backend error bodies. For HTTP 429, the tool returns parsed `Retry-After` guidance when available, or a generic wait-before-retrying message. It does not automatically retry or sleep.
|
|
499
|
+
|
|
500
|
+
**Workspace and folder inventory**
|
|
501
|
+
|
|
502
|
+
`core_list-items` calls the [Fabric Core List Items API](https://learn.microsoft.com/rest/api/fabric/core/items/list-items). Use it for a scoped metadata inventory, not for OneLake file/blob listing (`onelake_list-items`) or cross-workspace discovery (`core_search-catalog`).
|
|
503
|
+
|
|
504
|
+
| Argument | Required | Description |
|
|
505
|
+
|----------|----------|-------------|
|
|
506
|
+
| `workspace-id` | Yes | Nonempty workspace UUID; workspace names are not resolved. |
|
|
507
|
+
| `type` | No | Fabric item type, such as `Lakehouse` or `Notebook`. Omit for all types. New service-defined types are accepted without a client-side enum restriction. |
|
|
508
|
+
| `recursive` | No | Defaults to `true`, including nested folders. Set `false` for direct items only. |
|
|
509
|
+
| `root-folder-id` | No | Nonempty folder UUID. Omit to use the workspace root. |
|
|
510
|
+
| `continuation-token` | No | Token from a previous response, copied unchanged. Keep the same workspace and filters. |
|
|
511
|
+
|
|
512
|
+
```powershell
|
|
513
|
+
# First page of all workspace items, including nested folders.
|
|
514
|
+
fabmcp core list-items --workspace-id aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
|
|
515
|
+
|
|
516
|
+
# Direct Lakehouses in one folder, excluding its nested folders.
|
|
517
|
+
fabmcp core list-items --workspace-id aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb --root-folder-id bbbbbbbb-1111-2222-3333-cccccccccccc --type Lakehouse --recursive false
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
Each invocation returns exactly one page: an `items` array and any `continuationToken` and `continuationUri` supplied by Fabric. An empty array can still have a next page. Call again with `continuation-token` and unchanged filters to continue; this tool never fetches all pages automatically or follows the returned URI. Copy the token without decoding Base64 or changing existing percent escapes.
|
|
521
|
+
|
|
522
|
+
Items contain ID, display name, type, workspace ID, and available description, folder ID, logical ID, tags, and sensitivity-label ID. Optional null properties are omitted. No item data, definitions, or workload-specific properties are returned. The optional REST `include=DefaultIdentity` expansion is intentionally unsupported: it is neither requested nor serialized.
|
|
523
|
+
|
|
524
|
+
The caller needs workspace **Viewer** access. Delegated calls require `Workspace.Read.All` or `Workspace.ReadWrite.All`; the API supports user, service-principal, and managed identities. The tool preserves the server's configured authentication strategy, including its existing HTTP/OBO credential path. A `429` response retains its status and provides retry guidance when a valid `Retry-After` header is available; the tool does not retry automatically.
|
|
525
|
+
|
|
526
|
+
**Creating a workspace**
|
|
527
|
+
|
|
528
|
+
`core_create-workspace` implements [Create Workspace](https://learn.microsoft.com/rest/api/fabric/core/workspaces/create-workspace) with one `POST /v1/workspaces`, expecting a synchronous `201 Created` response.
|
|
529
|
+
|
|
530
|
+
| Parameter | Required | Behavior |
|
|
531
|
+
|-----------|----------|----------|
|
|
532
|
+
| `display-name` | Yes | Workspace display name, not empty or whitespace, at most 256 characters. Only unused names are allowed. `Admin monitoring` is reserved, including case variations and surrounding whitespace. |
|
|
533
|
+
| `description` | No | At most 4000 characters. An explicitly empty string is preserved. |
|
|
534
|
+
| `capacity-id` | No | Nonempty UUID of an existing capacity to assign during creation. Names are not resolved. |
|
|
535
|
+
| `domain-id` | No | Nonempty UUID of an existing domain to assign during creation. Names are not resolved. |
|
|
536
|
+
|
|
537
|
+
Omitted optional fields are not sent. The tool does not provision a capacity or domain, check name availability, call `assignToCapacity`, create items, or poll an operation.
|
|
538
|
+
|
|
539
|
+
These examples **create real workspaces** when run with authorized credentials. Replace the placeholders with existing resource IDs before using the second example:
|
|
540
|
+
|
|
541
|
+
```powershell
|
|
542
|
+
fabmcp core create-workspace --display-name "Sales Planning"
|
|
543
|
+
|
|
544
|
+
fabmcp core create-workspace --display-name "Capacity Analytics" `
|
|
545
|
+
--description "Analytics workspace" `
|
|
546
|
+
--capacity-id "<capacity-id>" `
|
|
547
|
+
--domain-id "<domain-id>"
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
The typed result contains `workspace` and, when supplied by Fabric, `location`. Workspace metadata includes ID, display name, type, and any returned description, capacity ID/region, domain ID, API endpoint, and applied tags. Missing optional metadata remains absent; the result does not infer capacity-assignment completion. Location and API endpoints are metadata only and are never followed. A valid workspace body succeeds even if the Location header is absent.
|
|
551
|
+
|
|
552
|
+
**Permissions:** The caller needs [workspace-creation permission](https://learn.microsoft.com/fabric/admin/portal-workspace#create-workspaces) granted by a Fabric administrator. When assigning a capacity, the caller needs [capacity contributor or admin permission](https://learn.microsoft.com/fabric/admin/capacity-settings#details). Domain assignment also requires the relevant domain permission. Delegated callers need `Workspace.ReadWrite.All`. For service principals, the administrator must enable [Service principals can create workspaces, connections, and deployment pipelines](https://learn.microsoft.com/fabric/admin/service-admin-portal-developer#service-principals-can-create-workspaces-connections-and-deployment-pipelines) for an allowed security group containing the principal. The separate **Service principals can call Fabric public APIs** setting alone does not grant workspace-creation permission. Admin access on an existing workspace is not the creation prerequisite.
|
|
553
|
+
|
|
554
|
+
**Failure handling:** Creation is mutating and not idempotent. The tool never automatically retries, including after throttling, and preserves failure status with sanitized messages and valid Retry-After guidance. A timeout, cancellation, network failure, or invalid success response can leave the creation outcome uncertain. Check whether the workspace exists before making another creation request. The tool is unavailable in read-only server mode.
|
|
555
|
+
|
|
556
|
+
**Updating workspace metadata**
|
|
557
|
+
|
|
558
|
+
* "Rename Fabric workspace \<workspace-id> to 'Finance Analytics' without changing its description"
|
|
559
|
+
* "Set the description of Fabric workspace \<workspace-id> to 'Quarterly reporting' without renaming it"
|
|
560
|
+
* "Clear the description of Fabric workspace \<workspace-id> and keep its display name"
|
|
561
|
+
|
|
562
|
+
`core_update-workspace` (`fabmcp core update-workspace`) implements the synchronous
|
|
563
|
+
[Update Workspace API](https://learn.microsoft.com/rest/api/fabric/core/workspaces/update-workspace).
|
|
564
|
+
It requires a nonempty workspace UUID and at least one update:
|
|
565
|
+
|
|
566
|
+
| Option | Behavior |
|
|
567
|
+
|--------|----------|
|
|
568
|
+
| `workspace-id` | Required workspace UUID; names and name resolution are not supported. |
|
|
569
|
+
| `display-name` | Optional name, up to 256 characters; cannot be empty or whitespace-only. Names must be unique within the tenant; `Admin monitoring` is reserved. |
|
|
570
|
+
| `description` | Optional description, up to 4000 characters. An empty string clears it. |
|
|
571
|
+
|
|
572
|
+
Omitted or null optional values are not sent and leave those properties unchanged. Supplied text is
|
|
573
|
+
not trimmed. For example, MCP arguments to clear only the description are:
|
|
574
|
+
|
|
575
|
+
```json
|
|
576
|
+
{ "workspace-id": "<workspace-id>", "description": "" }
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
The caller needs the **workspace Admin role** and, for delegated access, **Workspace.ReadWrite.All**.
|
|
580
|
+
This mutating tool is unavailable in read-only mode and uses the server's standard destructive-operation
|
|
581
|
+
confirmation. Its result contains `workspace` with only `id`, `displayName`, `type`, and `description`
|
|
582
|
+
when returned by Fabric; an empty returned description remains empty.
|
|
583
|
+
|
|
584
|
+
The tool makes one application-level PATCH with no application retries, prefetch, follow-up requests,
|
|
585
|
+
polling, or enrichment. The Fabric Core HTTP client does not automatically follow redirects.
|
|
586
|
+
Response URLs are not followed by application code. Capacity, domain,
|
|
587
|
+
identity, permissions, tags, endpoints, items, and data cannot be updated through this tool.
|
|
588
|
+
Failures retain the HTTP status and expose only sanitized messages and validated `Retry-After`
|
|
589
|
+
guidance. If a request times out or returns an invalid success payload, the update might already
|
|
590
|
+
have been applied; verify the workspace before manually retrying.
|
|
591
|
+
|
|
592
|
+
**Updating item metadata**
|
|
593
|
+
|
|
594
|
+
`core_update-item` implements [Update Item](https://learn.microsoft.com/rest/api/fabric/core/items/update-item):
|
|
595
|
+
one application-level `PATCH /v1/workspaces/{workspaceId}/items/{itemId}` with a synchronous `200` Item response.
|
|
596
|
+
It requires `workspace-id` and `item-id` as nonempty UUIDs, plus at least one of `display-name` or `description`.
|
|
597
|
+
It does not resolve names, fetch the item first, read item data, or change definitions, permissions, tags, or identity.
|
|
598
|
+
|
|
599
|
+
Omitted properties remain unchanged. An explicitly empty description clears it; JSON `null` is treated as omitted.
|
|
600
|
+
Descriptions may contain at most 256 characters and are not trimmed. Display names must not be empty or whitespace-only and must follow the item's
|
|
601
|
+
type-specific naming rules; there is no universal display-name length limit enforced by this tool.
|
|
602
|
+
For example, these MCP arguments clear only the description:
|
|
603
|
+
|
|
604
|
+
```json
|
|
605
|
+
{
|
|
606
|
+
"workspace-id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
|
|
607
|
+
"item-id": "5b218778-e7a5-4d73-8187-f10824047715",
|
|
608
|
+
"description": ""
|
|
609
|
+
}
|
|
610
|
+
```
|
|
611
|
+
|
|
612
|
+
The result contains an `item` with `id`, `displayName`, `type`, `workspaceId`, and an optional `description`.
|
|
613
|
+
Definitions, data, identities, tags, and workload-specific properties are not returned. Existing server output modes apply:
|
|
614
|
+
the default returns text content; compact and duplicated modes additionally expose the typed output schema and structured content.
|
|
615
|
+
|
|
616
|
+
The caller needs read and write permission on the item. Delegated callers need `Item.ReadWrite.All` or the corresponding
|
|
617
|
+
item-specific scope, such as `Notebook.ReadWrite.All`. Service-principal and managed-identity support depends on the item type.
|
|
618
|
+
The tool is mutating and idempotent, is unavailable in read-only mode, and uses the existing host authentication and confirmation policies.
|
|
619
|
+
It performs no automatic retry or long-running-operation polling. HTTP failures preserve their status and suppress backend details;
|
|
620
|
+
valid nonnegative integer `Retry-After` values provide wait guidance. After a timeout or invalid response, the update may already
|
|
621
|
+
have completed: verify the item's state before retrying.
|
|
622
|
+
The Fabric Core HTTP client does not automatically follow redirects.
|
|
623
|
+
|
|
624
|
+
#### Delete a Fabric item
|
|
625
|
+
|
|
626
|
+
`core_delete-item` sends one [Delete Item API](https://learn.microsoft.com/rest/api/fabric/core/items/delete-item) request. It does not resolve names, inspect item types, retry requests, or poll operations.
|
|
627
|
+
The Fabric Core HTTP client does not automatically follow redirects, including 307/308 responses that would otherwise repeat the DELETE.
|
|
628
|
+
|
|
629
|
+
| Parameter | Required | Behavior |
|
|
630
|
+
|-----------|----------|----------|
|
|
631
|
+
| `workspace-id` | Yes | Nonempty UUID of the workspace containing the item. |
|
|
632
|
+
| `item-id` | Yes | Nonempty UUID of the item to delete. |
|
|
633
|
+
| `hard-delete` | No | Omit to leave the API parameter unspecified, explicitly pass `false` to send `hardDelete=false`, or explicitly pass `true` to request permanent deletion. |
|
|
634
|
+
|
|
635
|
+
**Deletion is destructive in every mode.** Omission or `false` uses Fabric's default deletion behavior, which soft-deletes only supported item types. It does not guarantee that the item can be recovered. Rejected default/soft deletions are returned as errors; the tool never falls back to permanent deletion.
|
|
636
|
+
|
|
637
|
+
**Permanent deletion cannot be recovered.** The CLI requires an explicit value: `--hard-delete true`. A bare `--hard-delete`, invalid value, or repeated occurrence is rejected before authentication or deletion. MCP advertises an optional Boolean input and preserves the existing argument conversion behavior: an explicitly supplied string `"true"` or string array `["true"]` can also bind as one explicit true value. The command does not enforce the original JSON type. Omission, `null`, an empty value, and `false` never enable hard deletion; empty/invalid values are rejected.
|
|
638
|
+
|
|
639
|
+
Illustrative CLI syntax (replace the placeholders only when intentionally deleting an item):
|
|
640
|
+
|
|
641
|
+
```powershell
|
|
642
|
+
# Default API deletion behavior; recovery is not guaranteed.
|
|
643
|
+
fabmcp core delete-item --workspace-id "<workspace-uuid>" --item-id "<item-uuid>"
|
|
644
|
+
|
|
645
|
+
# Explicitly do not request permanent deletion.
|
|
646
|
+
fabmcp core delete-item --workspace-id "<workspace-uuid>" --item-id "<item-uuid>" --hard-delete false
|
|
647
|
+
|
|
648
|
+
# Explicitly request irreversible permanent deletion.
|
|
649
|
+
fabmcp core delete-item --workspace-id "<workspace-uuid>" --item-id "<item-uuid>" --hard-delete true
|
|
650
|
+
```
|
|
651
|
+
|
|
652
|
+
Soft deletion requires write permission on the item; hard/permanent deletion requires the workspace **Admin** role. Delegated callers need `Item.ReadWrite.All` or the corresponding item-specific write scope. Service principal and managed identity support depends on the item type. Existing host authentication and destructive-operation consent requirements apply; the tool is unavailable in read-only mode.
|
|
653
|
+
|
|
654
|
+
On the documented empty HTTP 200 response, the tool returns only `workspaceId`, `itemId`, and `hardDeleteRequested`. These identify the requested target and mode, not item metadata or a recovery guarantee. A 404 or other failure is an error, not a successful deletion. An upstream 400 reports Fabric rejection with item-state, soft-delete support, and tenant-setting guidance, not a missing-ID diagnosis. Throttling responses retain status 429 and include validated `Retry-After` guidance when available, without automatic retries. A genuinely canceled or timed-out request does not confirm deletion, but cancellation arriving after a completed HTTP 200 response does not discard that confirmation.
|
|
655
|
+
|
|
656
|
+
**Delete Workspace** implements the [Fabric Core Delete Workspace API](https://learn.microsoft.com/rest/api/fabric/core/workspaces/delete-workspace).
|
|
657
|
+
|
|
658
|
+
> [!WARNING]
|
|
659
|
+
> Deleting a workspace also deletes the items under it. Verify the exact workspace UUID and obtain authorization for that specific deletion before invoking this tool. No recovery, retention, or permanent-deletion semantics are promised by this tool.
|
|
660
|
+
|
|
661
|
+
The CLI command is `fabmcp core delete-workspace --workspace-id <workspace-uuid>`. Its only option, `workspace-id`, is required and must be a nonempty UUID. Invalid IDs are rejected before authentication or HTTP. Names, fuzzy lookup, implicit target selection, and bulk deletion are not supported.
|
|
662
|
+
|
|
663
|
+
The caller must have the **Admin** workspace role. Delegated callers additionally require **Workspace.ReadWrite.All**. The API documents support for users, service principals, and managed identities; this does not imply those identity flows have been exercised by the offline tests.
|
|
664
|
+
|
|
665
|
+
The tool sends one `DELETE /v1/workspaces/{workspaceId}` request with no body or automatic redirects. Only the documented synchronous, empty `200 OK` produces a typed acknowledgement: `{"workspaceId":"<canonical-workspace-uuid>","deleted":true}`. It does not read or deserialize a workspace response body, enumerate or individually delete items, change permissions, retry automatically, or poll. Failures retain their HTTP status and expose sanitized messages; 403 and 404 never count as successful deletion. An upstream 400 advises checking workspace state and tenant restrictions rather than claiming the validated UUID is missing. Validated `Retry-After` guidance can be returned for throttling. A genuinely canceled or timed-out request does not confirm the outcome; check the workspace state before attempting another deletion. A returned HTTP 200 still confirms success if cancellation arrives afterward.
|
|
666
|
+
|
|
667
|
+
The tool is marked destructive, not read-only, and idempotent in the no-additional-effects sense; repeated requests can still return 404. Read-only MCP servers hide and reject this tool. The existing MCP elicitation gate requires consent and rejects unsupported or declined consent unless explicitly disabled by the host's dangerous configuration. Annotations alone do not guarantee human confirmation, and direct CLI execution does not use the MCP elicitation gate. Implementation or test approval does not authorize real deletion; API-level tests use substituted HTTP and credentials only.
|
|
668
|
+
|
|
669
|
+
**Workspace capacity assignment**
|
|
670
|
+
|
|
671
|
+
Example prompt: "Submit a request to assign workspace \<workspace-id> to capacity \<capacity-id>; do not wait for completion."
|
|
672
|
+
|
|
673
|
+
`fabmcp core assign-workspace-to-capacity` requires both `--workspace-id` and `--capacity-id` as nonempty GUIDs. It uses [Assign To Capacity](https://learn.microsoft.com/rest/api/fabric/core/workspaces/assign-to-capacity) to send one POST with `{ "capacityId": "<target-capacity-id>" }`.
|
|
674
|
+
|
|
675
|
+
The documented response is **202 Accepted**, with no response body: assignment is in progress. The tool preserves status 202 and returns its own receipt:
|
|
676
|
+
|
|
677
|
+
```json
|
|
678
|
+
{
|
|
679
|
+
"workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff512",
|
|
680
|
+
"capacityId": "0f084df7-c13d-451b-af5f-ed0c466403b2",
|
|
681
|
+
"accepted": true,
|
|
682
|
+
"state": "Pending"
|
|
683
|
+
}
|
|
684
|
+
```
|
|
685
|
+
|
|
686
|
+
`capacityId` is the requested target, not a verified current assignment. The tool never reports completion, invents an operation handle, polls, or follows up automatically. A caller can later inspect `capacityId` and `capacityAssignmentProgress` through [Get Workspace](https://learn.microsoft.com/rest/api/fabric/core/workspaces/get-workspace). Assignment can still fail after acceptance.
|
|
687
|
+
|
|
688
|
+
The caller needs **workspace Admin** and **capacity Contributor or Admin** permissions, with both **Capacity.ReadWrite.All** and **Workspace.ReadWrite.All** scopes. The API supports users, service principals, and managed identities. Authentication uses the server's configured identity provider; remote OBO calls use the caller's permissions.
|
|
689
|
+
|
|
690
|
+
Workspaces containing Fabric items other than Power BI items cannot migrate across regions. Such workspaces can only be assigned to Fabric, Fabric trial, or Power BI Premium capacity. These restrictions are enforced by Fabric: the tool makes no preflight calls or eligibility guarantees. It does not create workspaces or provision, resize, or activate capacities; creating a workspace with a `capacityId` is a separate API operation.
|
|
691
|
+
|
|
692
|
+
Failures preserve the service's HTTP status and return sanitized guidance. On throttling, a valid `Retry-After` delay is reported without automatically retrying. If a timeout or network failure prevents confirmation, inspect the workspace before submitting again. The tool never chooses a different target capacity.
|
|
207
693
|
|
|
208
694
|
### Data Factory Operations
|
|
209
695
|
|
|
@@ -235,7 +721,15 @@ The Fabric MCP Server exposes tools organized into three categories:
|
|
|
235
721
|
|
|
236
722
|
## Security
|
|
237
723
|
|
|
238
|
-
The Fabric MCP Server is a **local-first** tool
|
|
724
|
+
The Fabric MCP Server is a **local-first** tool. Its documentation tools provide API specifications, schemas, and best practices without connecting to live Fabric environments. Operational tools, including Get Workspace, make authenticated requests using the server's configured identity and permissions.
|
|
725
|
+
|
|
726
|
+
`core_create-workspace` creates a real workspace and can assign it to an existing capacity and domain; review those arguments and use an appropriately authorized identity before invoking it.
|
|
727
|
+
|
|
728
|
+
`core_update-item` modifies an existing item's name or description; review its arguments and item permissions before use.
|
|
729
|
+
|
|
730
|
+
`core_delete-workspace` can delete a workspace and its items. Review the exact UUID, permissions, and destructive-operation controls before invoking it.
|
|
731
|
+
|
|
732
|
+
`core_assign-workspace-to-capacity` is a mutating control-plane operation. Verify both target IDs and permissions before invoking it; acceptance does not confirm completion.
|
|
239
733
|
|
|
240
734
|
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.
|
|
241
735
|
|
package/dist/fabmcp
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
[diffend] Oversized file quarantined before diffing.
|
|
2
2
|
name: package/dist/fabmcp
|
|
3
|
-
size:
|
|
4
|
-
sha256:
|
|
3
|
+
size: 84601328 bytes
|
|
4
|
+
sha256: c35e4990bcefbc56cd1fbae79460e9e5977a667cb79537def341951a95a8a9a0
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@microsoft/fabric-mcp-darwin-arm64",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.0",
|
|
4
4
|
"description": "Microsoft Fabric MCP Server - Model Context Protocol implementation for Fabric, for darwin on arm64",
|
|
5
5
|
"author": "Microsoft",
|
|
6
6
|
"homepage": "https://github.com/Microsoft/mcp/blob/main/servers/Fabric.Mcp.Server#readme",
|