close
Skip to main content
The Protocol Conformance SDK lets you run the same checks as the CLI protocol conformance commands, but inside your own Jest or Vitest suites. Use it when you want MCP protocol regressions to fail CI directly, or when you need JUnit XML and JSON artifacts from code rather than shell scripts.
Protocol conformance is currently HTTP-only. For local stdio-only servers, use MCP Apps Conformance, unit tests, or run your server through an HTTP bridge in CI.

​
Import

import {
  MCPConformanceSuite,
  MCPConformanceTest,
  renderConformanceReportJUnitXml,
  renderConformanceReportJson,
  toConformanceReport,
} from "@mcpjam/sdk";

​
Single run

const test = new MCPConformanceTest({
  serverUrl: "https://your-server.com/mcp",
  checkTimeout: 15_000,
  checkIds: [
    "server-initialize",
    "ping",
    "tools-list",
    "prompts-list",
    "resources-list",
  ],
});

const result = await test.run();

console.log(result.passed);
console.log(result.summary);
console.log(result.checks);

​
Suite

import { writeFileSync } from "node:fs";

const suite = new MCPConformanceSuite({
  name: "Protocol CI",
  serverUrl: "https://your-server.com/mcp",
  defaults: {
    checkTimeout: 15_000,
  },
  runs: [
    {
      label: "core-surface",
      checkIds: [
        "server-initialize",
        "ping",
        "tools-list",
        "prompts-list",
        "resources-list",
      ],
    },
    {
      label: "security",
      checkIds: [
        "localhost-host-rebinding-rejected",
        "localhost-host-valid-accepted",
      ],
    },
  ],
});

const result = await suite.run();
const report = toConformanceReport(result);

writeFileSync(
  "protocol-conformance.junit.xml",
  renderConformanceReportJUnitXml(report),
);
writeFileSync(
  "protocol-conformance.report.json",
  JSON.stringify(renderConformanceReportJson(report), null, 2),
);
MCPConformanceSuiteConfig keeps the existing serverUrl + defaults + runs shape:
PropertyTypeRequiredDescription
namestringNoSuite label shown in summaries and JUnit XML
serverUrlstringYesShared MCP HTTP server URL
defaultsPartial<Omit<MCPConformanceConfig, "serverUrl">>NoShared defaults applied to every run
runsArray<Partial<Omit<MCPConformanceConfig, "serverUrl">> & { label?: string }>YesIndividual run labels and check selections

​
MCPConformanceConfig

PropertyTypeRequiredDefaultDescription
serverUrlstringYesMCP server URL
accessTokenstringNoBearer access token
customHeadersRecord<string, string>NoExtra HTTP headers
checkTimeoutnumberNo15000Per-check timeout in ms
categoriesMCPCheckCategory[]Noall categoriesRestrict checks to categories
checkIdsMCPCheckId[]Noall checksRestrict checks to specific ids
fetchFntypeof fetchNofetchCustom fetch implementation
clientNamestringNoSDK defaultCustom MCP client name

​
Available categories and check ids

Categories:
  • core
  • protocol
  • tools
  • prompts
  • resources
  • security
  • transport
Check ids:
  • server-initialize
  • ping
  • logging-set-level
  • completion-complete
  • capabilities-consistent
  • tools-list
  • tools-input-schemas-valid
  • prompts-list
  • resources-list
  • protocol-invalid-method-error
  • localhost-host-rebinding-rejected
  • localhost-host-valid-accepted
  • server-sse-polling-session
  • server-accepts-multiple-post-streams
  • server-sse-streams-functional

​
Result types

MCPConformanceTest.run() returns an MCPConformanceResult:
PropertyTypeDescription
passedbooleanWhether all selected checks passed
serverUrlstringServer under test
checksMCPCheckResult[]Individual check results
summarystringHuman-readable summary
durationMsnumberTotal duration
categorySummaryRecord<MCPCheckCategory, ...>Pass/fail/skipped counts by category
MCPConformanceSuite.run() returns an MCPConformanceSuiteResult:
PropertyTypeDescription
namestringSuite name
serverUrlstringShared server URL
passedbooleantrue iff every run passed
resultsArray<MCPConformanceResult & { label: string }>Per-run results
summarystringHuman-readable suite summary
durationMsnumberTotal suite duration

​
CI reporting

All three conformance domains share the same report helpers:
  • toConformanceReport(result)
  • renderConformanceReportJUnitXml(report)
  • renderConformanceReportJson(report)
The CLI uses the same helpers internally, so protocol conformance --format junit-xml and protocol conformance-suite --format junit-xml emit the same XML that the SDK helpers produce for the same result.