@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.

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.
• Calls local MCP-compatible HTTP endpoints with JSON-RPC tools/call requests.
• Calls local stdio MCP-style processes with one JSON-RPC request per invocation.
• 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.

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 runtime authorization problems, 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.