adaptive-cards-mcp
Adaptive Cards MCP
An MCP server that helps AI assistants generate valid, accessible Adaptive Cards for Teams, Outlook, Copilot, and other Microsoft surfaces. 9 tools, 3 guided workflows, 924 tests.
Blog: I Built an MCP Server That Makes AI 10x Better at Adaptive Cards
Demo
Related MCP server: aifmt
Quick Start
No install needed — npx downloads and runs it automatically.
1. Add to your AI assistant
claude mcp add adaptive-cards-mcp -- npx adaptive-cards-mcpAdd to .vscode/mcp.json:
{
"servers": {
"adaptive-cards-mcp": {
"command": "npx",
"args": ["adaptive-cards-mcp"]
}
}
}Add to .cursor/mcp.json:
{
"mcpServers": {
"adaptive-cards-mcp": {
"command": "npx",
"args": ["adaptive-cards-mcp"]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"adaptive-cards-mcp": {
"command": "npx",
"args": ["adaptive-cards-mcp"]
}
}
}TRANSPORT=sse PORT=3001 npx adaptive-cards-mcp
# With auth enabled
TRANSPORT=sse MCP_API_KEY=your-secret npx adaptive-cards-mcpOpen Copilot Studio → your agent → Tools → Add a tool → New tool → Model Context Protocol
Enter your MCP server URL (e.g.,
https://your-server.azurewebsites.net/sse)Select the tools to expose
Enable Developer mode in ChatGPT settings
Go to Settings → Connectors → Create
Enter your MCP server HTTPS URL
2. Start using it
Just ask your AI assistant in natural language:
> Create an expense approval card for Teams> Convert this JSON data into an Adaptive Card table> Validate this card and fix accessibility issues> Make this card work on Outlook (v1.4)The AI picks the right tools, generates a valid card, validates it, and returns production-ready JSON you can paste directly into the Adaptive Cards Designer to preview.
Usage
Natural language (recommended)
Describe what you need — the AI figures out which tools to call:
Approvals and workflows:
> Create an expense approval card for Teams with requester photo, amount,
category, line items, and approve/reject/comment buttons> Build a time-off request card — employee name, dates, remaining PTO balance,
manager approval with optional rejection reasonNotifications and alerts:
> Create a CI/CD deployment notification: service name, environment, build number,
commit SHA, deploy status with rollback button> Generate a PagerDuty-style incident alert card — severity P1, affected service,
start time, on-call engineer, acknowledge/escalate actionsData and reports:
> Here's our Q1 sales data, turn it into a card:
[{"region":"APAC","revenue":1250000,"growth":"12%"},
{"region":"EMEA","revenue":980000,"growth":"8%"},
{"region":"Americas","revenue":2100000,"growth":"15%"}]> Convert this CSV to a card:
Employee,Department,Start Date,Status
Jane Kim,Engineering,2026-01-15,Active
Bob Lee,Design,2026-02-01,Active
Carol Wu,PM,2026-03-10,OnboardingForms and input:
> Create an employee onboarding checklist — new hire name, start date,
assigned buddy, IT setup tasks with checkboxes, and a submit button> Build a customer feedback survey card with a 1-5 star rating,
comment field, and NPS score dropdownProfiles and status:
> Create a team member profile card with photo, name, title, department,
skills tags, and contact buttons for email/chat/calendar> Build a service health dashboard card showing 5 microservices
with status indicators (healthy/degraded/down) and last check timeCross-host and versioning:
> This card works in Teams but breaks in Outlook — fix it
> Make this card work on Webex (v1.3 only, no Table, no Action.Execute)
> Downgrade this v1.6 card to v1.4 for Viva ConnectionsValidation and optimization:
> Validate this card and tell me what's wrong — I'm getting render errors
> Make this card accessible — it needs to work with screen readers
> This card is too complex, optimize it for performance and compact layoutWhat you say | What the AI calls |
"Create a leave approval card for Teams" |
|
"Here's my API response, make it a card" |
|
"Is this card valid for Outlook?" |
|
"Make this card accessible" |
|
"Convert this card to a reusable template" |
|
"This card needs to work on v1.3" |
|
"What layout should I use for a dashboard?" |
|
Slash commands (MCP prompts)
For guided, multi-step workflows, use the built-in prompts directly:
Create a card:
> /adaptive-cards-mcp:create-adaptive-card
description: "Expense approval with requester photo, line items table, total amount,
and approve/reject buttons with comment field"
host: teams
intent: approvalRuns: generate → validate → optimize → host config
> /adaptive-cards-mcp:create-adaptive-card
description: "CI/CD deployment notification with service name, environment,
build number, status badge, and rollback action"
host: teams
intent: notification> /adaptive-cards-mcp:create-adaptive-card
description: "Employee profile card with photo, name, title, department,
contact info, and skills tags"
host: outlook
intent: profileConvert data to a card:
> /adaptive-cards-mcp:convert-data-to-card
data: [
{ "task": "Review PR #482", "assignee": "Jane", "due": "2026-03-21", "status": "pending" },
{ "task": "Deploy hotfix v2.1.3", "assignee": "Bob", "due": "2026-03-19", "status": "in-progress" },
{ "task": "Update API docs", "assignee": "Carol", "due": "2026-03-22", "status": "done" }
]
title: "Sprint Tasks"
presentation: table> /adaptive-cards-mcp:convert-data-to-card
data: { "service": "api-gateway", "cpu": "92%", "memory": "78%", "requests": "12.4k/min",
"p99_latency": "245ms", "error_rate": "0.3%", "uptime": "99.97%" }
title: "Service Health — api-gateway"
presentation: factsRuns: analyze data → pick best layout → validate output
Review an existing card:
> /adaptive-cards-mcp:review-adaptive-card
card: { "type": "AdaptiveCard", "version": "1.6", "body": [...your card...] }
host: outlookRuns: validate schema + accessibility → auto-fix issues → summary report
npm library (programmatic)
For use in your own code (bots, APIs, CI pipelines), install the package:
npm install adaptive-cards-mcpimport { generateCard, validateCardFull, dataToCard, optimizeCard } from 'adaptive-cards-mcp';
const result = await generateCard({
content: "Create a flight status card",
host: "teams",
intent: "display"
});
console.log(result.card); // Adaptive Card JSON
console.log(result.cardId); // Reference ID for subsequent calls
console.log(result.validation); // Schema + accessibility + host compatSee the Library API reference for full details.
What you get back
Card-producing tools return two clean blocks — card JSON you can copy, and a metadata summary:
```json
{
"type": "AdaptiveCard",
"version": "1.6",
"body": [ ... ],
"actions": [ ... ]
}
```
---
**Validation:** Valid
**Accessibility Score:** 100/100
**Elements:** 7 | **Nesting Depth:** 2 | **Version:** 1.6
**Card ID:** card-abc123
**Steps:** generate → validate → optimize
**Try it out:** Paste the card JSON into the [Adaptive Cards Designer](https://adaptivecards.microsoft.com/designer)
**Local Preview:** file:///tmp/ac-preview-xyz.htmlTools, Prompt and Usage
Reference
MCP Tools (9)
Tool | Description |
| Natural language / data → valid Adaptive Card v1.6 JSON |
| Schema validation + accessibility score + host compatibility + suggested fixes |
| Auto-select Table / FactSet / Chart / List from data shape |
| Improve accessibility, performance, modernize actions |
| Static card → |
| Version upgrade/downgrade, host-config adaptation |
| Recommend best layout pattern for a description |
| Generate + validate + optionally optimize in one call |
| Multi-step pipeline: generate → optimize → template → transform |
MCP Prompts (3)
Prompt | Pipeline | Slash command |
| generate → validate → optimize → host config |
|
| validate → auto-fix → before/after report |
|
| analyze data → pick presentation → validate |
|
MCP Resources (5) + Templates (2)
Resource | Description |
| Complete JSON Schema for Adaptive Cards v1.6 |
| Host compatibility matrix for all 7 hosts |
| Single host compatibility info |
| 36 curated example cards catalog |
| Examples filtered by intent |
| 21 canonical layout patterns |
| Session card store (cards by cardId) |
Host Compatibility
Host | Max Version | Notes |
Generic | 1.6 | Default — no host-specific constraints |
Teams | 1.6 | Max 6 actions, Action.Execute preferred |
Outlook | 1.4 | Limited elements, max 4 actions |
Web Chat | 1.6 | Full support |
Windows | 1.6 | Subset of elements |
Viva Connections | 1.4 | SPFx-based ACE framework |
Webex | 1.3 | No Table, no Action.Execute |
Configuration
Environment Variable | Description | Default |
| Transport mode: |
|
| HTTP port for SSE transport |
|
| API key for HTTP auth | (disabled) |
| Auth mode: | (disabled) |
| Anthropic Claude API key | (deterministic mode) |
| OpenAI API key | (deterministic mode) |
| Azure OpenAI API key | (disabled) |
| Azure OpenAI endpoint URL | (disabled) |
| Ollama local model URL | (disabled) |
| Enable debug logging: | (disabled) |
| Enable rate limiting: |
|
| Enable telemetry: |
|
| PostHog project API key for remote reporting | (disabled) |
| PostHog API host |
|
Note: When used via MCP (Claude Code, Copilot, Cursor), the host LLM provides the intelligence — no API key needed. Set an API key only for standalone/library usage.
Telemetry & Privacy
Telemetry is opt-in and disabled by default. When enabled, the server collects anonymous usage metrics and sends aggregated data to PostHog to help improve the project.
How to enable:
VS Code extension: A one-time consent prompt appears on first install. You can change it anytime in Settings → Adaptive Cards → Telemetry.
CLI / MCP server: Set
MCP_TELEMETRY=truein your environment, or edit~/.adaptive-cards-mcp/config.jsonand set"telemetry": true.
What is sent: Tool names, call counts, durations, error rates, platform (OS), Node version, package version, transport type.
What is never sent: Card content, user prompts, data payloads, IP addresses, file paths, environment variables.
A random session ID is generated each time the server starts — no persistent identifier is stored across sessions.
To disable: Set MCP_TELEMETRY=false or leave unconfigured (default is off).
Development
cd packages/core
npm install
npm run build # TypeScript + copy data files
npm test # 924 tests (vitest)
npm run test:coverage # With coverage report
npm run lint # TypeScript type check
npm run lint:eslint # ESLint check
npm run format # Prettier formattingLocal Testing
Smoke test all tools and prompts:
./test-mcp-tools.sh --local # 28 tests — all 9 tools with real-world scenarios
./test-mcp-prompts.sh --local # 10 tests — all 3 prompts (guided workflows)
./test-mcp-tools.sh # same tests against published npm package
./test-mcp-prompts.sh # same tests against published npm packageMCP Inspector (visual UI):
cd packages/core && npm run build
npx @modelcontextprotocol/inspector node dist/server.js
# Opens http://localhost:6274 — pick a tool, enter params, click RunTerminal (stdio):
cd packages/core
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"generate_card","arguments":{"content":"expense approval card","intent":"approval","host":"teams"}}}' \
| node dist/server.js 2>/dev/null | tail -1 | python3 -m json.toolSSE mode:
TRANSPORT=sse PORT=3001 node packages/core/dist/server.js
curl http://localhost:3001/healthArchitecture
packages/core/src/
├── server.ts # MCP server (stdio + SSE, 9 tools, 3 prompts)
├── index.ts # Library exports
├── types/ # TypeScript interfaces
├── core/ # Schema validator, analyzer, accessibility, host compat
├── generation/ # 21 layout patterns, data analyzer, assembler, LLM client
├── tools/ # 9 tool handlers
├── utils/ # Logger, input guards, rate limiter, card store, auth, telemetry, preview
└── data/ # v1.6 schema, 36 examples, host configsEcosystem
Package | Description |
MCP server + npm library (9 tools) — npm | |
VS Code extension — adaptive-cards-ai-vscode |
What's New in v2.3.0
Accessibility 100/100 — All generated cards now include
speakproperty automaticallyNo more broken JSON — Newlines in content sanitized, titles no longer truncate at version numbers
Host-aware generation —
generate_and_validateauto-downgrades card version for Outlook (v1.4), Webex (v1.3)CSV fix — CSV data correctly parsed before building FactSet/Table cards
Telemetry —
/metricsendpoint with session tracking, per-tool call distribution, host/intent usageMCP Registry — Listed on the official MCP Registry
E2E test suite — 28 tool tests + 10 prompt tests with quality gates (a11y score, element count)
See the full CHANGELOG for details.
Links
npm — Install and package details
GitHub — Source code, issues, and contributions
MCP Registry — Official MCP server listing
Related Projects
AdaptiveCards-Mobile — Cross-platform Adaptive Cards renderer
openclaw-adaptive-cards — OpenClaw AI agent plugin using this library
Adaptive Cards Documentation — Official docs
Adaptive Cards Designer — Interactive card designer
Adaptive Cards Schema Explorer — Interactive schema reference
License
MIT
Available Tools
9 toolscard_workflowC
Execute a multi-step card pipeline in a single call. Steps: generate, validate, optimize, template, transform.
Inputs: steps (required), content, data, host, +1 more.
data_to_cardA
Convert structured data (JSON array, CSV, key-value object) into the optimal Adaptive Card presentation.
Inputs: data (required), presentation, title, host, +1 more.
generate_and_validateA
Generate an Adaptive Card and immediately validate + optionally optimize it in a single call. Reduces tool-call overhead for common workflows.
Inputs: content (required), data, host, intent, +2 more.
generate_cardB
Convert any content — natural language description, structured data, or a combination — into a valid Adaptive Card v1.6 JSON. Returns cardId for reference in subsequent tool calls.
Inputs: content (required), data, host, theme, +2 more.
optimize_cardC
Optimize an existing Adaptive Card. Accepts card JSON or a cardId.
Inputs: card (required), goals, host.
suggest_layoutC
Recommend the best Adaptive Card layout pattern for a given description.
Inputs: description (required), constraints.
template_cardB
Convert a static Adaptive Card into an Adaptive Card Template with ${expression} data binding.
Inputs: card, dataShape, description.
transform_cardB
Transform an Adaptive Card: upgrade/downgrade version, apply host-specific constraints, or flatten nesting.
Inputs: card (required), transform (required), targetVersion, targetHost.
validate_cardA
Validate an Adaptive Card JSON against the v1.6 schema. Returns diagnostics with suggested fixes for each error. Accepts card JSON or a cardId from a previous tool call.
Inputs: card (required), host, strictMode.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
generate_card and data_to_card overlap significantly since generate_card already accepts structured data, and generate_and_validate/card_workflow both wrap similar generation/validation pipelines. The boundaries between convenience wrappers and the individual tools they wrap are unclear, making tool selection ambiguous.
Most tools follow a verb_noun pattern like validate_card, generate_card, optimize_card, and transform_card, and all names use snake_case. However, generate_and_validate (verb_and_verb), data_to_card (noun_to_noun), and card_workflow (noun_noun) break the dominant convention, creating a mixed but still readable naming scheme.
Nine tools is a reasonable size for an Adaptive Card authoring/processing server and sits comfortably in the ideal range. The count is slightly inflated by redundant convenience wrappers, but the overall scale is appropriate for the domain.
The server covers generation, validation, optimization, transformation, templating, and layout suggestion, which covers most core authoring workflows. However, there is no way to retrieve/list stored cards despite cardId references, and no tool to apply a generated template to data, leaving notable gaps in the lifecycle.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for VertaaUX.ai — run UX & accessibility audits, generate fixes, and monitor quality from your LLM or IDE. 38 tools covering the full audit-to-fix lifecycle across 7 UX categories.29MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that fixes, validates, and generates visual text content for AI coding assistants.MIT
- AlicenseAqualityDmaintenanceMCP server to help AI assistants generate Italian PA user interfaces by providing components, recipes, accessibility rules, and validation for Bootstrap Italia and Web Components.9European Union Public 1.2
- AlicenseNot gradedqualityDmaintenanceMCP server that exposes a design system and UX rulebook as tools, enabling AI to generate UI consistent with your design tokens, components, layout rules, accessibility guidelines, and templates. It also provides a review tool to score UI proposals against the design system.MIT