Praxa MCP contracts for governed AI agent tools

@praxa/mcp-contracts is a zero-dependency package containing 12 Model Context Protocol tool definitions for the Praxa Integration Gateway. It targets MCP 2025-11-25, negotiates compatibility with 2025-03-26, and gives agent hosts stable schemas, scopes, route metadata, idempotency rules, and tool annotations without embedding credentials or execution authority.

Choose how to integrate

Goal	Use	What it proves
Inspect or register stable tool definitions	`@praxa/mcp-contracts`	Package and host-adapter compatibility
Let an MCP host execute Praxa tools	Deployment-specific remote `/mcp`	Transport, OAuth, Gateway, and runtime behavior after canaries
Build directly with TypeScript mission helpers	`@praxa/sdk`	Typed Integration Gateway client behavior
Submit a minimal public durable task	Execution Fabric `/v1`	Public API admission and run lifecycle

Install the contracts

npm install @praxa/mcp-contracts

What the package includes

The package exports everything you need to describe Praxa tools to an MCP host:

PRAXA_MCP_TOOLS — A Praxa-branded export alias for the 12 stable Aura-compatible wire definitions. Each PraxaMcpTool object contains the tool name, description, inputSchema (JSON Schema), annotations, operationId, HTTP method and path, required OAuth scope, and idempotency behavior.
praxaMcpTool(name) — A lookup function that returns a single tool definition by name, or undefined if the name is not found.
MCP_PROTOCOL_VERSION — The primary protocol revision, "2025-11-25".
MCP_LEGACY_PROTOCOL_VERSION — The negotiated compatibility revision, "2025-03-26".
MCP_SUPPORTED_PROTOCOL_VERSIONS — Both supported revisions in preference order.
MCP_SERVER_NAME — The stable wire identifier "aura-agent-os", retained for compatibility.
MCP_SERVER_VERSION — The package/server software version, currently "0.3.0"; this is distinct from the negotiated protocol revision.
JSON-RPC message types — JsonRpcRequest, JsonRpcResponse, and JsonRpcId TypeScript types for building MCP server implementations on top of these contracts.

Understand protocol and wire identity

These contracts target MCP protocol version 2025-11-25 using JSON-RPC 2.0 as the transport framing and can negotiate compatibility with 2025-03-26:

import {
  MCP_LEGACY_PROTOCOL_VERSION,
  MCP_PROTOCOL_VERSION,
  MCP_SERVER_NAME,
  MCP_SERVER_VERSION,
} from "@praxa/mcp-contracts";

console.log(MCP_PROTOCOL_VERSION);        // "2025-11-25"
console.log(MCP_LEGACY_PROTOCOL_VERSION); // "2025-03-26"
console.log(MCP_SERVER_NAME);             // "aura-agent-os"
console.log(MCP_SERVER_VERSION);          // "0.3.0"

The package and TypeScript aliases use Praxa branding, while the published wire identifiers remain Aura-compatible: tool names use the aura_* prefix and MCP_SERVER_NAME is "aura-agent-os". Treat those values as protocol identifiers, not display branding. Connect an MCP 2025-11-25 Streamable HTTP client to the hosted /mcp endpoint and authenticate using a delegated Praxa OAuth token scoped to the specific operations your agent requires. Clients that only support 2025-03-26 can negotiate that compatibility revision.

Understand the execution boundary

@praxa/mcp-contracts contains protocol contracts only. The package defines tool schemas and metadata — it does not include server execution logic, OAuth authority, provider adapters, or action executors. To actually execute the tools described here, you need a running Praxa Integration Gateway. The contracts tell your MCP host what each tool accepts and returns; the gateway is what carries out the work.

@praxa/mcp-contracts is licensed under Apache-2.0 and is safe to vendor directly into your project or redistribute as part of your own MCP server package. The tool definitions carry no embedded credentials or environment dependencies.

MCP quickstart

Install the package, run a contract test, choose an execution path, and complete a safe-read canary.

MCP Tools Reference

Full table of all 12 tool definitions with scopes, paths, and usage examples

Host setup guides

Configure Claude Code, Cursor, VS Code, OpenAI, or another MCP host.

Business and developer use cases

Choose the right tools and completion evidence for common workflows.

Integrate the MCP contracts

Register the stable Aura-compatible wire identifiers in an agent host and verify schemas, annotations, scopes, and protocol versions.

Frequently asked questions

Is `@praxa/mcp-contracts` an MCP server?

No. It is the exact package of tool definitions and protocol constants. Use a configured Praxa Integration Gateway for remote execution or implement a host adapter and executor in trusted server code.

Why do the wire names begin with `aura_`?

They are compatibility identifiers retained across the Praxa rebrand. Keep them byte-identical even when the host displays Praxa branding.

Can I use a Praxa Execution Fabric key with remote MCP?

No. Remote MCP uses the deployment’s delegated OAuth authority. Fabric keys, Gateway tokens, and provider credentials are intentionally not interchangeable.

Should all 12 tools be enabled?

Usually not. Start with the smallest safe-read allowlist, add mutations only for a defined use case, and require approval plus authoritative readback.

​Choose how to integrate

​Install the contracts

​What the package includes

​Understand protocol and wire identity

​Understand the execution boundary

MCP quickstart

MCP Tools Reference

Host setup guides

Business and developer use cases

Integrate the MCP contracts

​Frequently asked questions

​Is @praxa/mcp-contracts an MCP server?

​Why do the wire names begin with aura_?

​Can I use a Praxa Execution Fabric key with remote MCP?

​Should all 12 tools be enabled?

Choose how to integrate

Install the contracts

What the package includes

Understand protocol and wire identity

Understand the execution boundary

Frequently asked questions

Is `@praxa/mcp-contracts` an MCP server?

Why do the wire names begin with `aura_`?

Can I use a Praxa Execution Fabric key with remote MCP?

Should all 12 tools be enabled?