MCP integration

Compatibility: Pactmark 0.1.x. @pactmark/mcp supports tested stdio and Streamable HTTP transports. Without a production SandboxAdapter, stdio remains preview-only.

The rule that governs everything here

Discovery never grants authority.

An MCP server tells you what it offers. It does not tell you what your agent is allowed to do. Those are separate facts and Pactmark keeps them separate: discovered metadata is untrusted input that must survive validation before a tool is ever exposed to the model. Figure 1. Boundary 6 is the one this page is about. Everything a server sends you — tool names, schemas, descriptions, pagination cursors, process output — arrives on the untrusted side.

Pinning a server

Host configuration pins the identity and the capabilities. Nothing is inferred:

const server = {
  id: "docs-search@1",
  transport: {
    kind: "http",
    origin: "https://mcp.internal.example.com", // exact HTTPS origin
    allowRedirects: false,
    credentialSlot: "mcp.docs",
  },
  protocol: { version: "2025-06-18" },
  allowedTools: ["search_documents", "get_document"],
  limits: {
    maxDiscoveryPages: 4,
    maxResponseBytes: 512_000,
    requestTimeoutMs: 5_000,
  },
};

Exact origin

Traffic goes through the egress broker to one normalized HTTPS origin. Cross-origin redirects are denied.

Origin-bound credentials

A credential issued for this origin cannot be replayed against another one.

Explicit tool allowlist

A server that starts offering a new tool does not gain access to your agent.

Bounded pages and bytes

Cursor loops and oversized responses are terminated, not absorbed.

stdio transport

Stdio is stricter, because it is a local process:

Requirement	Why
Absolute executable path	No `PATH` resolution, no shim substitution
Fixed argument list	No interpolation from discovered content
Minimal environment	The child does not inherit your secrets
Bounded output and time	A chatty or hung server cannot exhaust the host
Guaranteed cleanup	Orphaned processes are a resource-exhaustion path

Without a production SandboxAdapter, treat stdio MCP as preview only. A local process is arbitrary code execution with your process’s privileges, and the reference container fixture is explicitly not production isolation — see Sandbox boundary.

What fails closed, and when

All of these are rejected before a tool becomes visible to the model:

Malformed discovery pages

A response that does not validate is not partially trusted.

Duplicate tool identities

Two tools claiming the same identity is an error, not a last-write-wins race.

Cursor loops

Pagination that does not terminate hits the bounded page limit.

Unknown risk metadata

A tool whose risk class you cannot interpret is not exposed. Unknown means no.

Schema drift

A tool whose schema changed under an existing registration no longer matches its digest.

Mapping an MCP tool into Pactmark

An MCP tool does not arrive with a Pactmark ToolSecurity declaration — you write one. That is the point: you are asserting the risk class, data classes, scopes, egress posture and limits, and your assertion is what policy enforces.

const searchDocuments = registerMcpTool({
  server,
  remoteName: "search_documents",
  id: "docs.search@1",
  implementationVersion: "1.0.0",
  input: searchInput,
  output: searchOutput,
  security: {
    riskClass: "R1",
    dataClasses: ["internal"],
    reversibility: "not_applicable",
    requiredScopes: ["docs:search"],
    egress: {
      mode: "allowlist",
      destinations: ["https://mcp.internal.example.com"],
      methods: ["POST"],
      credentialSlots: ["mcp.docs"],
    },
    networkEnforcement: "required",
    maxCallsPerRun: 6,
    timeoutMs: 5_000,
  },
});

Treat returned content as hostile

Indirect prompt injection through tool output is threat model row TM-02, and it is rated critical. The controls are structural rather than textual:

returned content is admitted into context under explicit byte bounds;
it carries no authority and cannot create a grant;
it cannot select an egress destination;
purpose, data class and egress profiles remain those of the work order, not of the content.

Semantic manipulation inside admitted data remains a model risk. Pactmark bounds the blast radius; it does not make a model immune to persuasion.

What to test

// Malformed discovery response → tool not exposed.
// Duplicate tool identity → registration refused.
// Cursor loop → bounded and terminated.
// Redirect to another origin → denied.
// Credential replay against a second origin → denied.
// Schema drift under an existing registration → digest mismatch.
// Cancellation mid-call → process cleaned up, no orphan.

Threat model

Row TM-14 covers malicious MCP metadata, drift, cursor loops and transport redirects.

Sandbox boundary

Why the reference container is a test fixture and not isolation.

Getting started

Core concepts

Guides

Deployment

Production

Security

The rule that governs everything here

Pinning a server

Exact origin

Origin-bound credentials

Explicit tool allowlist

Bounded pages and bytes

stdio transport

What fails closed, and when

Mapping an MCP tool into Pactmark

Treat returned content as hostile

What to test

Threat model

Sandbox boundary

​The rule that governs everything here

​Pinning a server

Exact origin

Origin-bound credentials

Explicit tool allowlist

Bounded pages and bytes

​stdio transport

​What fails closed, and when

​Mapping an MCP tool into Pactmark

​Treat returned content as hostile

​What to test

Threat model

Sandbox boundary

The rule that governs everything here

Pinning a server

stdio transport

What fails closed, and when

Mapping an MCP tool into Pactmark

Treat returned content as hostile

What to test