Install

Install mcpose, its peer dependency, and the optional audit package. Then verify the install with a runnable proxy before wiring up your client.

Prerequisites

• Node.js 20 or newer.
• @modelcontextprotocol/sdk ^1.17.0 as a peer dependency, installed separately below.
• TypeScript is optional - mcpose ships ESM with first-class types.

Install

# core
npm install mcpose

# peer dependency - installed separately
npm install @modelcontextprotocol/sdk@"^1.17.0"

# compliance audit trails (optional)
npm install @mcpose/audit

For the compliance test helpers, install @mcpose/testing as a dev dependency:

npm install --save-dev @mcpose/testing

Verify it works

Save the Quick Start proxy as proxy.ts:

import { createBackendClient, startProxy } from 'mcpose';
import type { ToolMiddleware } from 'mcpose';

// 1 · Connect to the upstream MCP server (stdio)
const backend = await createBackendClient({
  command: 'node',
  args: ['/path/to/backend-server.mjs'],
});

// 2 · Define middleware - before and after the upstream call
const logging: ToolMiddleware = async (req, next) => {
  console.error(`→ ${req.params.name}`);
  const result = await next(req);
  console.error(`← ${req.params.name} done`);
  return result;
};

// 3 · Start the proxy on stdio
await startProxy(backend, {
  name: 'my-proxy',
  toolMiddleware: [logging],
});

Run it:

npx tsx proxy.ts

Point any client at it:

{
  "mcpServers": {
    "governed-search": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/proxy.ts"]
    }
  }
}

Versions

These docs target mcpose@3.0.0, released with all seven companion packages. See the migration guide for the exact version matrix and breaking changes. Core requires @modelcontextprotocol/sdk ^1.17.0. Audit 3.0.0 writes audit format v2; historical format-v1 archives need their pinned 2.x verifier.

mcpose/testing vs @mcpose/testing

Two similarly named entry points, no relation:

• mcpose/testing is a subpath of the core package: in-memory backend and pipeline helpers for proxy tests, createMockBackendClient and runToolMiddleware. See mcpose/testing.
• @mcpose/testing is a separate package: keyless compliance assertions for the audit chain, assertAuditChainIntegrity, assertReplayManifestValid, assertPiiRedacted, and assertDelegationHonored. See @mcpose/testing.

Next steps