@peac/mcp-server

@peac/mcp-server

MCP tool server for signed interaction receipt operations: verify, inspect, decode, issue, and bundle.

Installation

pnpm add @peac/mcp-server

Or run directly:

npx @peac/mcp-server

What It Does

@peac/mcp-server exposes PEAC receipt operations as Model Context Protocol (MCP) tools that AI agents and LLM-based applications can call. It supports both stdio and Streamable HTTP transports, with static policy enforcement, concurrency limits, input size guards, and structured error responses with recovery hints.

How Do I Use It?

Add to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "peac": {
      "command": "npx",
      "args": ["-y", "@peac/mcp-server"]
    }
  }
}

Add to Cursor or Windsurf

Add to .mcp.json at your project root:

{
  "mcpServers": {
    "peac": {
      "command": "npx",
      "args": ["-y", "@peac/mcp-server"]
    }
  }
}

Streamable HTTP transport

npx @peac/mcp-server --transport http --port 3000

HTTP transport provides per-session isolation, rate limiting, and RFC 9728 PRM discovery. Binds to 127.0.0.1 by default. See examples/mcp-http-quickstart/ for an end-to-end demo.

Enable receipt issuance

npx @peac/mcp-server \
  --issuer-key env:PEAC_ISSUER_KEY \
  --issuer-id https://example.com

Start with HTTP transport

npx @peac/mcp-server --transport http --port 3000

MCP tools

Tool	Description	Availability
peac_verify	Verify a receipt JWS signature and claims	Always
peac_inspect	Inspect receipt structure and metadata	Always
peac_decode	Decode a receipt JWS without verification	Always
peac_issue	Sign and return a new receipt JWS	Requires --issuer-key and --issuer-id
peac_create_bundle	Create a signed evidence bundle directory	Requires --issuer-key, --issuer-id, and --bundle-dir

All tool responses include _meta with serverVersion, policyHash, protocolVersion, and registeredTools.

CLI options

Flag	Description	Default
--transport <type>	Transport: stdio or http	stdio
--port <number>	HTTP port	3000
--host <address>	HTTP bind address	127.0.0.1
--issuer-key <ref>	Issuer key reference (env:VAR or file:/path)	None
--issuer-id <uri>	Issuer identifier URI	None
--policy <path>	Policy configuration file path	Built-in default
--jwks-file <path>	JWKS file for verifier key resolution	None
--bundle-dir <path>	Directory for evidence bundle output	None
--cors-origins <list>	Allowed CORS origins (comma-separated, HTTP only)	None
--trust-proxy <value>	Trust X-Forwarded-For (off, loopback, private)	off

Programmatic usage

Handlers can be used directly without the MCP server binding:

import { createPeacMcpServer, handleVerify } from '@peac/mcp-server';
import { getDefaultPolicy, computePolicyHash } from '@peac/mcp-server';

const policy = getDefaultPolicy();
const policyHash = await computePolicyHash(JSON.stringify(policy));

const result = await handleVerify({
  input: { jws: 'eyJ...', public_key_base64url: '...' },
  policy,
  context: {
    version: '0.12.4',
    policyHash,
    protocolVersion: '0.2',
  },
});

Integrates With

• @peac/protocol (Layer 3): Receipt issuance and verification
• @peac/crypto (Layer 2): JWS signing and decoding
• @peac/schema (Layer 1): Receipt schema validation
• @peac/kernel (Layer 0): Error codes and constants
• @modelcontextprotocol/sdk: MCP server and transport bindings

For Agent Developers

Connect your agent to this server over stdio or HTTP to gain receipt verification, decoding, and issuance capabilities. The tools use structured outputs with error codes and next_action recovery hints so your agent can handle failures programmatically. Every response includes _meta for audit and traceability.

Read-only tools (peac_verify, peac_inspect, peac_decode) are available with no configuration. To enable issuance, provide an Ed25519 signing key via --issuer-key and --issuer-id.

For Operators

The server enforces static policy with configurable concurrency limits, input size bounds, JWS size caps, and tool timeouts. HTTP transport binds to localhost by default with CORS deny-all. The stdout fence prevents non-JSON-RPC output from corrupting the stdio transport.

Security properties: no ambient key discovery (keys must be explicitly provided), no implicit network fetches from tool handlers, path traversal prevention on bundle output, and session isolation on HTTP transport.

License

Apache-2.0

PEAC Protocol is an open source project stewarded by Originary and community contributors.

Docs | GitHub | Originary