@axtary/mcp

MCP tool provenance helpers for Axtary's local runtime plane.

Early 0.x release: the runtime path is real and tested, but the API is not stable yet and may change between minor versions.

The source repository is currently private. Public product documentation and runnable guides are at axtary.com/docs.

npm install @axtary/mcp

This package keeps transport execution behind Axtary's policy and ledger path. It normalizes MCP tool definitions and calls into Axtary actions, then provides local JSON-RPC HTTP/stdio invokers and fixture handlers that execute only after the proxy has evaluated policy, issued an ActionPass, written the ledger, and rechecked the tool definition hash.

What It Does

• Normalizes MCP tool definitions with server identity, schema version, name, description, and input schema.
• Computes deterministic sha256: definition hashes.
• Creates mcp.tool.call normalized Axtary actions with toolDefinition provenance.
• Wraps MCP-style tool invokers as Axtary proxy handlers.
• Connects to upstream MCP servers over stdio (McpStdioClient) or the Streamable HTTP transport (McpHttpClient, spec 2025-06-18: session id + protocol-version headers, application/json or SSE responses) behind one transport-agnostic McpUpstreamClient interface.
• Refuses cleartext http:// to non-loopback hosts (assertSafeMcpUrl) so upstream credentials are never sent in the clear.
• Keeps network access explicit: the HTTP invoker, HTTP client, and OAuth discovery/registration/token helpers all require a caller-injected fetch-compatible transport and fail closed without one. Spawning a wrapped stdio MCP server (child process + inherited environment) remains the package's core local function.
• Provides fixture-backed handlers for deterministic demos and tests.
• Fails closed if the action's tool name, server identity, schema version, or definition hash no longer matches the registered tool.
• Persists reviewed definition hashes to a pin manifest (axtary.mcp_pins.v1, upgraded in place from v0) and reconciles a server's current definitions against it (reconcileMcpPins), so drift between sessions is detected — pinned / new / drifted — not just within one run.
• Optionally verifies signed, versioned tool definitions (axtary.mcp_signed_definition.v1): a publisher signs the exact definitionHash, a semantic version, the required scopes, and a priorDefinitionHash link to the version it supersedes, using ES256/JOSE. Unsigned, mis-signed, unknown-key, or altered definitions fail closed before invoke via createSignedMcpToolHandler. See spec/mcp-tool-provenance-v1.md.
• Evaluates the version chain (evaluateMcpVersionChain): a new signed version is continuous only if it references the pinned version's hash and bumps its semver; otherwise it is surfaced as broken_chain or version_not_incremented (rug-pull defense), never silently accepted.
• Binds verified publisher provenance (publisher / publisherKeyId / semver / priorDefinitionHash) into the normalized action's toolDefinition, so it rides into the ActionPass and the ledger and is independently verifiable from the ledger alone. These fields are optional: a hash-only tool produces a byte-identical toolDefinition to before.
• Persists verifier-side publisher trust as public-only, 0600 JSON (saveMcpPublisherTrustStore) and loads a signed-definition registry mapping (serverIdentity, toolName) to an expected publisher and compact JWS. The operator CLI consumes these primitives; signatures never use trust on first use.
• Defines a secret-free live conformance receipt/registry (axtary.mcp_conformance_receipt.v0) for per-server proof: pinned tools, governed call digest, ActionPass v1/DPoP ledger evidence, labeled synthetic drift quarantine, and verified signed attestation.

Quickstart

This example runs as-is with Node 20+:

import { createMcpToolDefinition, createMcpAction } from "@axtary/mcp";

// Pin the tool definition: server identity, schema version, name, description,
// and input schema all hash together into one definition hash.
const definition = createMcpToolDefinition({
  serverIdentity: "mcp://internal/payments",
  schemaVersion: "2026-03-26",
  name: "refund_customer",
  description: "Issues a refund for an order.",
  inputSchema: { type: "object", properties: { orderId: { type: "string" } } },
});
console.log(definition.definitionHash);

// Every call becomes a normalized action carrying that provenance, so a
// mutated tool definition (tool poisoning) breaks the hash and is denied.
const action = createMcpAction({
  definition,
  call: { toolName: "refund_customer", arguments: { orderId: "ord_123" } },
  actor: {
    agentId: "agent:claude-code",
    humanOwner: "user:[email protected]",
    runtime: "claude-code",
    tenant: "org:example",
  },
  intent: { taskId: "TASK-1", declaredGoal: "Refund duplicate charge" },
});
console.log(action.capability.tool, action.toolDefinition.definitionHash === definition.definitionHash);

Design Notes

MCP tool poisoning and schema drift are content-authorization problems at execution time, not just connection setup problems. Axtary records the tool definition hash in the action and checks it again at execution time, so a changed tool schema requires a fresh policy/approval path. The pin manifest makes that guarantee durable: a tool is trusted-on-first-use (or, in strict mode, only after explicit review), and any later change to its definition is quarantined until a human re-pins it — drift cannot be laundered by restarting the wrapper.

Conformance receipts are local evidence, not connection inventory. They never persist upstream headers or tool response content, and operator surfaces must treat old receipts as stale rather than implying continuous health.

Signed definitions add publisher identity on top of the content hash. The hash answers "did this definition change?"; the signature answers "did a publisher I trust attest to this exact version, and how does it relate to the last one I pinned?". This is the Axtary profile of the ETDI idea (arXiv:2506.01333), expressed on ES256/JOSE. Trust is exactly the publisher keys an operator configures — there is no trust-on-first-use for signatures (that stays at the human-reviewed pin layer). A signature attests to who published a definition and its version lineage; it does not prove the tool is safe and does not detect prompt injection.