MCP Apps Conformance & Debugging

Validate MCP Apps tool metadata, ui:// resources, and App Builder rendering from the CLI

The apps conformance command validates the server-side MCP Apps surface your server exposes through tools and ui:// resources.

The apps debug command executes one app tool and can drive the local Inspector App Builder to render the resulting UI. Together, these commands cover MCP Apps triage, CI checks, fast regression detection, and local render reproduction.

This is currently server-side MCP Apps conformance only. A passing run does not prove full SEP-1865 host behavior such as ui/initialize, ui/notifications/tool-input ordering, sandbox proxy behavior, or host display-mode handling.

Quick start

mcpjam apps conformance --url https://your-server.com/mcp

For a local stdio server:

mcpjam apps conformance --command node --args server.js --cwd /path/to/project

You can emit CI-friendly JUnit XML from either the single-run or suite command:

mcpjam apps conformance \
  --url https://your-server.com/mcp \
  --format junit-xml > apps-report.xml

To reproduce one tool result in the local Inspector:

mcpjam apps debug \
  --url https://your-server.com/mcp \
  --tool-name create_view \
  --params '{"projectId":"demo"}' \
  --ui \
  --format json

What it checks

The current runner validates:

1. MCP Apps tools are present.
2. Tool metadata uses valid _meta.ui.resourceUri and visibility values.
3. Tool inputSchema is a non-null JSON Schema object.
4. Listed UI resources use ui:// URIs and text/html;profile=mcp-app.
5. Referenced UI resources can be fetched with resources/read.
6. Resource contents provide exactly one HTML payload via text or blob.
7. _meta.ui.csp, permissions, domain, and prefersBorder use valid shapes.

Example output

mcpjam apps conformance \
  --url https://your-server.com/mcp \
  --format json

Typical success summary:

{
  "passed": true,
  "summary": "7/7 checks passed, 0 failed, 0 skipped",
  "discovery": {
    "toolCount": 3,
    "uiToolCount": 1,
    "listedResourceCount": 1,
    "listedUiResourceCount": 1,
    "checkedUiResourceCount": 1
  }
}

Suite runner

Use apps conformance-suite when you want a named CI matrix from a config file.

Example config:

{
  "name": "Apps CI",
  "target": {
    "url": "https://your-server.com/mcp",
    "timeout": 30000
  },
  "defaults": {
    "checkIds": ["ui-tools-present", "ui-tool-metadata-valid"]
  },
  "runs": [
    {
      "label": "metadata"
    },
    {
      "label": "resources",
      "checkIds": [
        "ui-resources-readable",
        "ui-resource-contents-valid",
        "ui-resource-meta-valid"
      ]
    }
  ]
}

Run it with:

mcpjam apps conformance-suite \
  --config ./apps-conformance.json \
  --format junit-xml > apps-report.xml

target uses the same shared server shape as the rest of the CLI, so it can point at either:

• an HTTP target with url
• a stdio target with command, optional args, optional env, and optional cwd

Categories and check ids

Two categories are available:

• tools
• resources

Specific check ids:

• ui-tools-present
• ui-tool-metadata-valid
• ui-tool-input-schema-valid
• ui-listed-resources-valid
• ui-resources-readable
• ui-resource-contents-valid
• ui-resource-meta-valid

Use --category to run a subset by category, or --check-id to run specific checks.

# Tool-only checks
mcpjam apps conformance \
  --url https://your-server.com/mcp \
  --category tools

# Specific checks
mcpjam apps conformance \
  --url https://your-server.com/mcp \
  --check-id ui-resources-readable \
  --check-id ui-resource-contents-valid

If you pass both --category and --check-id, the explicit --check-id selection wins.

Debug one app render

Use apps debug when a conformance result is not enough and you need to inspect the output of one MCP App tool call.

Without --ui, the command executes the tool through the SDK and returns structured JSON with:

• tools: how many tools were listed and whether the requested tool was found
• toolMetadata and ui: the metadata used to identify MCP Apps or OpenAI Apps UI resources
• execution: the actual tool result

With --ui, the CLI starts or attaches to the local Inspector, connects the target server, opens App Builder, injects the already-completed tool result, and requests a UI snapshot.

mcpjam apps debug \
  --command node --args server.js --cwd /path/to/project \
  --tool-name create_view \
  --params @params.json \
  --ui \
  --protocol mcp-apps \
  --device desktop \
  --theme light \
  --out app-debug.json \
  --format json

apps debug --ui executes the server tool once. Inspector receives the completed result through renderToolResult, so the UI render path does not call the tool a second time.

If the command returns success: false with an error, check whether the failure came from execution or from inspectorRender. A render failure can coexist with a successful tool execution.

Large tool results can appear in execution, the render command result, and the final snapshot. Use --out <path> when sharing artifacts with agents, issue trackers, or CI logs.

Shared connection flags

apps conformance and apps debug use the same shared target flags as the rest of the CLI:

Flag	Description
--transport <transport>	Explicit transport type (http or stdio)
--url <url>	HTTP MCP server URL
--access-token <token>	Bearer access token
--oauth-access-token <token>	OAuth bearer access token
--refresh-token <token>	OAuth refresh token
--client-id <id>	OAuth client ID (with --refresh-token)
--client-secret <secret>	OAuth client secret (with --refresh-token)
--header <header>	HTTP header in Key: Value format (repeatable)
--client-capabilities <json>	Client capabilities JSON object
--command <command>	Command for a stdio server
--args <arg...>	Preferred stdio command arguments
--command-args <arg>	Legacy stdio command argument (repeatable)
-e, --env <env...>	Stdio environment KEY=VALUE values
--cwd <path>	Working directory for the stdio child process

Stdio child processes inherit the parent shell environment by default. Use -e/--env to add values or override inherited ones when the app server needs project-specific configuration. --transport is optional; without it, --url implies HTTP and --command implies stdio.

Notes

• The runner always advertises the MCP Apps UI extension capability so servers do not hide their MCP Apps surface when custom client capabilities are provided.
• Deprecated _meta["ui/resourceUri"] is accepted but reported as a warning.
• Tool name SHOULD validations (length, character set, uniqueness) surface as warnings, not failures.
• permissions are validated against the SEP-1865 object shape, for example geolocation: {} instead of booleans.
• Exit codes are CI-friendly: 0 when all selected checks pass, 1 when any check fails, and 2 for invalid command usage or config files.

Related commands

• Server inspection for breadth-first connectivity and capability triage
• Tools, resources & prompts for direct connected checks
• Command reference for the full flag list