Integrate Praxa Capabilities with MCP-Compatible Agents

Praxa ships first-class MCP (Model Context Protocol) 2025-11-25 support, with negotiated 2025-03-26 compatibility, via the @praxa/mcp-contracts package. The package exports the full set of typed tool definitions — names, input schemas, required scopes, and HTTP operation metadata — so you can register Praxa capabilities with any MCP-compatible server or agent framework in a few lines of code, without having to hand-craft JSON Schema or maintain route mappings yourself.

The @praxa/mcp-contracts package contains protocol-only contracts. It defines what the tools look like and what they require; it does not include server-side execution logic or provider credentials. Your application is responsible for routing each tool invocation to a PraxaClient instance that holds a valid access token.

Installing MCP Contracts

npm install @praxa/mcp-contracts

The package has no runtime dependencies and is safe to import in both Node.js and edge environments.

Available MCP Tools

PRAXA_MCP_TOOLS exports all 12 definitions in the Praxa MCP tool surface. The wider Integration Gateway also includes transport operations that are not MCP tools. The table below lists each MCP tool, the operation it maps to, and the OAuth scope your access token must carry for the call to be authorised.

Tool name	Operation	Required scope
`aura_submit_intent`	Record natural-language intent for deterministic compilation	`missions:write`
`aura_create_mission`	Submit a new agent mission	`missions:write`
`aura_get_mission`	Read a mission projection by `runId`	`missions:read`
`aura_signal_mission`	Send a named signal to a running mission	`missions:write`
`aura_cancel_mission`	Request durable mission cancellation	`missions:write`
`aura_search_capabilities`	Search policy-eligible capability manifests	`capabilities:read`
`aura_query_memory`	Query purpose-filtered memory	`memory:read`
`aura_get_skill`	Read a versioned governed skill	`skills:read`
`aura_get_trace`	Read a redacted causal trace	`traces:read`
`aura_list_goals`	List context-twin goals	`context:read`
`aura_list_world_certificates`	List signed model capability certificates	`world:read`
`aura_get_coverage`	Read reference coverage evidence	`coverage:read`

Each entry in the array also carries inputSchema (a JSON Schema object), operationId, method, path, idempotency, and an optional pathArgument field that names the input key to interpolate into the URL path.

Registering Tools with Your MCP Server

Use PRAXA_MCP_TOOLS as the source for your server’s registration loop. Each inputSchema is raw JSON Schema draft 2020-12; convert it through the adapter required by your chosen MCP server library.

import { PRAXA_MCP_TOOLS, MCP_PROTOCOL_VERSION } from "@praxa/mcp-contracts";
import { PraxaClient } from "@praxa/sdk";

const praxaClient = new PraxaClient({
  baseUrl: process.env.PRAXA_BASE_URL!,
  accessToken: () => process.env.PRAXA_ACCESS_TOKEN!,
});

// Framework-neutral pseudocode: adapt raw JSON Schema to your MCP host API.
for (const tool of PRAXA_MCP_TOOLS) {
  mcpHost.registerJsonSchemaTool({
    name: tool.name,
    description: tool.description,
    inputSchema: tool.inputSchema,
    annotations: tool.annotations,
  }, async (args) => {
    // Route to PraxaClient based on operationId
    switch (tool.operationId) {
      case "submitIntent":
        return praxaClient.submitIntent(args.intent, args.idempotencyKey);
      case "createMission":
        return praxaClient.createMission(
          { goalSpec: args.goalSpec, resourceBudget: args.resourceBudget },
          args.idempotencyKey,
        );
      case "getMission":
        return praxaClient.getMission(args.runId);
      case "signalMission":
        return praxaClient.signalMission(args.runId, args.signal, args.payload, args.idempotencyKey);
      case "cancelMission":
        return praxaClient.cancelMission(args.runId, args.reason, args.idempotencyKey);
      case "searchCapabilities":
        return praxaClient.searchCapabilities({ actionFamily: args.actionFamily, purpose: args.purpose, targetType: args.targetType });
      case "queryMemory":
        return praxaClient.queryMemory(args);
      case "getSkill":
        return praxaClient.getSkill(args.skillId);
      case "getTrace":
        return praxaClient.getTrace(args.traceId);
      case "listGoals":
        return praxaClient.listGoals();
      case "listWorldModelCertificates":
        return praxaClient.listWorldModelCertificates();
      case "getReferenceCoverage":
        return praxaClient.getReferenceCoverage();
      default:
        throw new Error(`Unknown Praxa operation: ${tool.operationId}`);
    }
  });
}

console.log(`Registered ${PRAXA_MCP_TOOLS.length} Praxa tools (MCP ${MCP_PROTOCOL_VERSION})`);

The registration loop is framework-neutral pseudocode because MCP server libraries accept raw JSON Schema through different adapters. Preserve tool.annotations when converting the schema so read-only, destructive, idempotent, and open-world hints reach the host.

You can narrow which tools you expose by filtering the array before iterating. For example, to register only read-only tools in a restricted context:

const readOnlyTools = PRAXA_MCP_TOOLS.filter(
  (tool) => tool.idempotency === "safe-read",
);

Looking Up a Single Tool

Use praxaMcpTool() to retrieve the definition for a single tool by name. This is useful when you need to inspect the input schema or required scope for a specific operation without importing the full array.

import { praxaMcpTool } from "@praxa/mcp-contracts";

const createMissionTool = praxaMcpTool("aura_create_mission");

if (createMissionTool) {
  console.log("Tool name:", createMissionTool.name);
  console.log("Required scope:", createMissionTool.requiredScope); // "missions:write"
  console.log("Idempotency:", createMissionTool.idempotency);       // "required"
  console.log("Input schema:", createMissionTool.inputSchema);
}

praxaMcpTool() returns undefined if no tool with the given name exists, so it is safe to use in conditional registration logic.

Protocol Version

The package exports protocol revisions separately from the server wire name and software version:

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"

Pass MCP_PROTOCOL_VERSION to your server’s handshake or capability advertisement to prefer MCP 2025-11-25. Negotiate MCP_LEGACY_PROTOCOL_VERSION only for a 2025-03-26 client. Use MCP_SERVER_NAME when configuring client discovery or logging so that your server identifies itself consistently.

The package and TypeScript exports use Praxa branding, but the stable wire identifiers remain Aura-compatible: MCP_SERVER_NAME is "aura-agent-os" and tool names use aura_*. Always register the exported values unchanged.

Add Praxa tools to an agent

Register the exact 12 published wire contracts in a Vercel AI SDK, OpenAI, LangChain, or framework-neutral host and test schema fidelity.

Get started

Core Concepts

Releases

Integrate Praxa Capabilities with MCP-Compatible Agents

Installing MCP Contracts

Available MCP Tools

Registering Tools with Your MCP Server

Looking Up a Single Tool

Protocol Version

Add Praxa tools to an agent

​Installing MCP Contracts

​Available MCP Tools

​Registering Tools with Your MCP Server

​Looking Up a Single Tool

​Protocol Version

Add Praxa tools to an agent

Installing MCP Contracts

Available MCP Tools

Registering Tools with Your MCP Server

Looking Up a Single Tool

Protocol Version