Add Praxa tools to an agent

• @praxa/mcp-contracts contains 12 protocol-only tool definitions.
• @praxa/sdk contains createPraxaAgentTools(), which binds the same operations to a PraxaClient.

​

Prerequisites

• the exact published Praxa package versions used by the tutorial;
• a trusted agent host with explicit tool, approval, timeout, and output policies;
• deployment-specific OAuth or backend-owned provider clients where the selected lane requires them;
• synthetic tenant, subject, prompt, and tool fixtures for positive and adversarial tests;
• an acceptance assertion that proves the host registers 12 exact tools and passes safe-read, wrong-scope, approval, and replay canaries.

​

1. Install and create the client

npm install @praxa/sdk@0.3.0 @praxa/mcp-contracts@0.3.0

import { createPraxaAgentTools, PraxaClient } from "@praxa/sdk";

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

const definitions = createPraxaAgentTools(client);

​

2. Connect an agent framework

import { jsonSchema, tool, ToolLoopAgent } from "ai";

const tools = Object.fromEntries(
  definitions.map((definition) => [
    definition.name,
    tool({
      description: definition.description,
      inputSchema: jsonSchema(definition.inputSchema),
      execute: definition.execute,
      needsApproval: !definition.readOnly,
    }),
  ]),
);

const agent = new ToolLoopAgent({ model, tools });
const result = await agent.generate({ prompt: "Prepare the weekly review" });
console.log(result.text);

const response = await openai.responses.create({
  model: "your-reviewed-model",
  input: "Prepare the weekly review",
  tools: [{
    type: "mcp",
    server_label: "praxa",
    server_url: `${process.env.PRAXA_BASE_URL}/mcp`,
    authorization: process.env.PRAXA_ACCESS_TOKEN,
    require_approval: "always",
  }],
});

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

for (const definition of PRAXA_MCP_TOOLS) {
  host.registerJsonSchemaTool({
    name: definition.name,
    description: definition.description,
    inputSchema: adaptJsonSchema(definition.inputSchema),
    annotations: definition.annotations,
  }, (args) => dispatchToPraxaClient(definition.operationId, args));
}

​

3. Preserve the wire identifiers

import {
  MCP_PROTOCOL_VERSION,
  MCP_LEGACY_PROTOCOL_VERSION,
  MCP_SERVER_NAME,
  MCP_SERVER_VERSION,
  PRAXA_MCP_TOOLS,
} 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
console.log(PRAXA_MCP_TOOLS[0].name);      // aura_submit_intent

​

4. Start with read-only tools

const readOnlyDefinitions = definitions.filter(
  (definition) => definition.readOnly,
);

​

5. Verify the integration

import { strict as assert } from "node:assert";
import {
  MCP_PROTOCOL_VERSION,
  MCP_SERVER_NAME,
  MCP_SERVER_VERSION,
  PRAXA_MCP_TOOLS,
} from "@praxa/mcp-contracts";

assert.equal(PRAXA_MCP_TOOLS.length, 12);
assert.equal(MCP_PROTOCOL_VERSION, "2025-11-25");
assert.equal(MCP_SERVER_NAME, "aura-agent-os");
assert.equal(MCP_SERVER_VERSION, "0.3.0");
assert.ok(PRAXA_MCP_TOOLS.every((tool) => tool.name.startsWith("aura_")));
assert.ok(PRAXA_MCP_TOOLS.every((tool) => tool.annotations));

1. List tools and require all expected exported wire names.
2. Invoke a safe read with the matching scope.
3. Invoke that read without its scope and require 403.
4. Invoke a keyed mutation twice with the same body and require one logical mutation.
5. Change the body while reusing the key and require a conflict.
6. Revoke the token and require subsequent tool calls to fail closed.
7. Confirm the framework never receives or logs a provider credential.

​

Troubleshooting

​

Best practices

• Enable the smallest tool or source set needed for the workflow.
• Require approval for mutations and independently for destructive actions.
• Derive tenant, subject, purpose, and credential from trusted host context.
• Bound tool inputs, output bytes, concurrent calls, retries, and total turn time.
• Verify a run, event, trace, receipt, or source status independently of model prose.

​

Optimize for production

• Reduce tool definitions and provider sources to the relevant set before each turn.
• Use deterministic filtering and pagination before placing results in model context.
• Cache only versioned, non-sensitive contracts and read-only metadata.
• Measure tool-selection accuracy, approval rate, p50/p95 call latency, context bytes, retries, and verified completion.

​

Cleanup and next steps

1. Revoke disposable delegated grants and remove test host configuration.
2. Delete provider fixtures through the provider’s own lifecycle when applicable.
3. Disable mutation tools until their negative and approval tests pass again after upgrades.
4. Retain only redacted tool, run, trace, and receipt identifiers needed for evaluation.

​

Frequently asked questions

​

What proves this tutorial works?

​

Can a browser, mobile app, or model prompt hold the credential?

​

How should an ambiguous mutation be retried?

​

What should we monitor after release?