mcp-apps · microsoft — Claude Code plugin: MCP tools and widgets
mcp-apps writes the server runtime for a codeful MCP tool, its JSON registration sidecar, and an HTML widget that shows the results — with or without CDN libraries.
MIT ★ 1,167 updated 2026-10-29
/plugin marketplace add microsoft/power-platform-skills
/plugin install mcp-apps@power-platform-skillsWhat mcp-apps does
Two skills come with this plugin. /generate-codeful-mcp-tool produces the server side of an MCP tool as a pair: <tool-name>.tool.js holds the runtime, <tool-name>.tool.json holds registration data. /generate-mcp-app-ui builds one HTML file that renders whatever the tool returns.
Schemas stay out of the code. inputSchema covers the whole toolInput object, outputSchema describes only the business payload the model gets to see. Annotations are always written, and openWorldHint is pinned to false because the runtime is fenced off: no imports, no network, no filesystem, no environment variables, nothing kept between calls. For Dataverse-backed tools the skill checks table and column names through PAC CLI, writes a temporary RuntimeTypes.ts during generation and deletes it afterwards.
Widget generation starts with one question: are public CDNs allowed? Saying no is the recommended route for MCP Inspector and hosts with tight content security policies, since the MCP Apps runtime and Fluent theme tokens get inlined and visuals are drawn with plain HTML, CSS, SVG or Canvas. Allow CDNs and the file shrinks, but a strict policy will block it and the widget shows nothing. Ask for a widget inside the same /generate-codeful-mcp-tool request and one pass gives you all three files.
What it helps with
- generate the server runtime for an MCP tool from a written spec
- register a tool with input and output JSON Schema plus annotations
- draw a chart from
structuredContentinside one HTML file - look up Dataverse table and column names before writing any code
- build a widget that opens under a strict CSP in MCP Inspector
Example prompts for the agent
- Use
/generate-codeful-mcp-toolto buildaccount-summary: it takesnameContainsandlimitup to 100, searches accounts, and returns name, revenue and status. - Build the widget with
/generate-mcp-app-ui: bar chart of revenue per account, no CDNs, here is the test output. - One request to
/generate-codeful-mcp-tool: give me the tool plus a sortable table widget.
How to install mcp-apps
Plugin marketplace
/plugin marketplace add microsoft/power-platform-skills/plugin install mcp-apps@power-platform-skillsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about mcp-apps
How do I install mcp-apps in Claude Code?
Add the marketplace with /plugin marketplace add microsoft/power-platform-skills, then run /plugin install mcp-apps@power-platform-skills.
What is mcp-apps for?
It bundles two skills: one generates the runtime and JSON sidecar for a codeful MCP tool, the other generates an HTML widget that visualizes that tool's output.
Do I need PAC CLI?
Only for tools that read Dataverse. The skill calls PAC CLI to resolve table and column logical names and builds a temporary RuntimeTypes.ts, which is removed once generation finishes.
Source text
mcp-apps · MIT
# MCP Apps Tool and Widget Generator
Generate JavaScript server runtimes and JSON Schema registration metadata for codeful MCP
tools, plus single-file HTML widgets that visualize their results. Widgets can embed
their runtime for restrictive hosts or use public CDNs when explicitly allowed.
## Installation
### From the marketplace
```bash
/plugin marketplace add microsoft/power-platform-skills
/plugin install mcp-apps@power-platform-skills
```
### From a local clone
```bash
copilot --plugin-dir /path/to/power-platform-skills/plugins/mcp-apps
# or
claude --plugin-dir /path/to/power-platform-skills/plugins/mcp-apps
```
## Skills
### Generate a codeful MCP tool
Run `/generate-codeful-mcp-tool` with the tool's purpose, inputs, expected result, and any
Dataverse data it needs:
```text
/generate-codeful-mcp-tool Create a tool named account-summary.
It accepts nameContains (string) and limit (integer, maximum 100), queries matching
accounts, and returns their names, revenue, and status.
```
For Dataverse-backed tools, the skill uses PAC CLI to discover exact table logical names
and generates a temporary `RuntimeTypes.ts` for verified columns, lookup shapes, and choice
values. The type file is removed after generation. The final output is a matched pair:
- `<tool-name>.tool.js` contains the self-contained runtime.
- `<tool-name>.tool.json` contains the tool registration metadata and MCP tool annotations.
The JavaScript file exports:
```javascript
export async function runTool({ toolInput, dataApi }) {
// Complete server implementation.
}
```
The runtime is self-contained: no packages, imports, network access, filesystem access,
environment variables, or persistent state.
The JSON sidecar keeps registration concerns out of executable code:
```json
{
"name": "account-summary",
"description": "Search accounts by name and return revenue and status summaries.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"inputSchema": {
"type": "object",
"properties": {}
},
"outputSchema": {
"type": "object",
"properties": {}
}
}
```
`inputSchema` describes the complete `toolInput` object and its validation constraints.
`outputSchema` describes only the model-visible `structuredContent` business payload. It
does not include conversational `content`, authored `meta`, or runtime `_meta`.
`annotations` always includes `readOnlyHint`, `destructiveHint`, `idempotentHint`, and an
`openWorldHint` fixed to `false` for the constrained codeful runtime.
### Generate an MCP App widget
Run `/generate-mcp-app-ui`, describe the visual, and provide the tool's test output:
```text
/generate-mcp-app-ui Show account revenue as a bar chart.
Here is the tool's test output:
{
"content": "Found 2 accounts.",
"structuredContent": {
"accounts": [
{ "name": "Contoso", "revenue": 1500000 },
{ "name": "Fabrikam", "revenue": 2300000 }
]
},
"meta": { "preferredView": "bar-chart" }
}
```
The skill asks whether public CDN URLs are allowed. **No CDNs / self-contained** is the
recommended default for MCP Inspector and other hosts with restrictive content security
policies. In that mode, the generated HTML embeds the MCP Apps runtime and Fluent theme
tokens, uses native HTML/CSS/SVG/Canvas for visuals, and has no runtime library downloads.
If CDNs are allowed, the skill retains the smaller CDN-based output.
The UI skill accepts:
- a plain object representing `structuredContent`;
- an authoring envelope with `content`, `structuredContent`, and `meta`; or
- a runtime MCP result with `content`, `structuredContent`, and `_meta`.
`content` and `structuredContent` are visible to the model. Authored `meta` becomes runtime
`_meta`, which is available to the widget but excluded from model context.
### Generate both
Ask `/generate-codeful-mcp-tool` for a widget in the same request. After validating the
paired tool files, it invokes the UI skill with a representative normalized result. The
outputs remain separate: one `.tool.js` server runtime, one `.tool.json` metadata
sidecar, and one `.html` widget.
## Codeful tool result contract
For a simple structured result, return a plain object. The host promotes it to
`structuredContent`:
```javascript
return { records, totalCount: records.length };
```
Use an envelope when the result channels need different visibility:
```javascript
return {
content: `Found ${records.length} records.`,
structuredContent: { records },
meta: { preferredView: "table" },
};
```
The envelope keys are reserved. If business data itself contains `content`,
`structuredContent`, or `meta`, wrap the payload explicitly in `structuredContent`.
## What it produces
- A self-contained `.tool.js` for codeful server logic and a matching `.tool.json`
registration sidecar.
- Optionally, a single `.html` widget using `@modelcontextprotocol/ext-apps`, either
embedded with no CDN dependencies or loaded from public CDNs with Fluent UI Web
Components.
See [`samples/account-summary.tool.js`](samples/account-summary.tool.js) and
[`samples/account-summary.tool.json`](samples/account-summary.tool.json) for a complete
paired tool example, [`samples/flight-status-widget.html`](samples/flight-status-widget.html)
for a read-only widget, and
[`samples/weather-refresh-widget.html`](samples/weather-refresh-widget.html) for an
interactive CDN widget. The marker-based
[`samples/self-contained-widget.template.html`](samples/self-contained-widget.template.html)
shows the source shape used before the bundled runtime is inlined.
## Skill structure
```text
skills/generate-codeful-mcp-tool/SKILL.md - Server runtime generator
skills/generate-mcp-app-ui/SKILL.md - Widget generator
references/codeful-tool-host-data-api.d.ts - Injected server API contract
references/mcp-apps-reference.md - MCP Apps result and lifecycle patterns
references/design-guidelines.md - Visual design defaults
assets/self-contained/mcp-app-runtime.min.js - Vendored no-CDN browser runtime
scripts/inline-self-contained-runtime.js - Deterministic single-file composer
scripts/_vendor-build/ - Pinned runtime rebuild tooling
samples/account-summary.tool.js - Codeful tool example
samples/account-summary.tool.json - Tool registration metadata example
samples/flight-status-widget.html - Read-only widget example
samples/weather-refresh-widget.html - Interactive widget example
samples/self-contained-widget.template.html - No-CDN source template
```
## Evals
- [`evals/mcp-apps/generate-codeful-mcp-tool/`](../../evals/mcp-apps/generate-codeful-mcp-tool/)
covers server generation, Dataverse access, result channels, errors, and UI handoff.
- [`evals/mcp-apps/generate-mcp-app-ui/`](../../evals/mcp-apps/generate-mcp-app-ui/)
covers widget types, result envelopes, private metadata, and type-mismatch stress cases.
Each suite includes `evals.json` and an `eval-runbook.md`.
## Maintaining the self-contained runtime
The no-CDN runtime is committed at
`assets/self-contained/mcp-app-runtime.min.js`. It is generated code; do not edit it by
hand. Its pinned build inputs live under `scripts/_vendor-build/`.
After intentionally changing a dependency version:
```bash
cd plugins/mcp-apps/scripts/_vendor-build
npm ci
npm run build
npm run check
```
Review `PROVENANCE.json` and `THIRD-PARTY-NOTICES.md` with every runtime update. Normal
widget generation does not install packages: it uses the committed bundle through
`scripts/inline-self-contained-runtime.js`. That script also supports `--prepare` to
replace the embedded runtime region with the editable source marker before refining an
existing widget.
## License
See the [LICENSE](../../LICENSE) file for license information.
© Microsoft · MIT · microsoft/power-platform-skills
Similar plugins
All plugins for Agent setup: memory, context, orchestration →mcp-apps by other authors comes first.