Mastra agent example

Connect a runnable Mach-1 client and discover tools available to its scoped credential.

Create a client with the following files. Set MACH1_MCP_URL=https://build.aioncx.com/api/mcp and MACH1_API_KEY to a personal scoped ingest key from Build Developers. Keep a separate key for each customer. For a key that grants multiple workspaces, append ?workspace_id=<workspace-id> to the MCP URL.

Install

Use Node.js 22.17 or later. In a new directory:

npm init -y
npm pkg set type=module
npm install --save-exact @mastra/core@1.75.0 @mastra/mcp@2.2.0 @modelcontextprotocol/client@2.0.0 tsx@4.20.6

Connect

Save this as client.ts. It uses the supported protocol, bounded timeouts, and output-schema validation. The key stays in the HTTP authorization header.

client.ts

import { MCPClient } from "@mastra/mcp";
import { AjvJsonSchemaValidator } from "@modelcontextprotocol/client/validators/ajv";

const url = process.env.MACH1_MCP_URL;
const key = process.env.MACH1_API_KEY;
if (!url || !key) throw new Error("Set MACH1_MCP_URL and MACH1_API_KEY.");

export const schemaValidator = new AjvJsonSchemaValidator();
export const mcp = new MCPClient({
  servers: {
    mach1: {
      url: new URL(url),
      protocolVersion: "legacy",
      connectTimeout: 30_000,
      requestInit: { headers: { Authorization: `Bearer ${key}` } },
      timeout: 660_000,
      jsonSchemaValidator: schemaValidator,
    },
  },
});

Save this as smoke.ts to check the connection without generating an agent response or submitting a conversation:

smoke.ts

import { mcp } from "./client.js";

try {
  const tools = await mcp.listTools();
  const names = Object.keys(tools);
  if (!names.some(name => name.includes("mach1_get_transport"))) throw new Error("Mach-1 transport tool unavailable");
  process.stdout.write(`${JSON.stringify({ connected: true, tools: names }, null, 2)}\n`);
} finally {
  await mcp.disconnect();
}

Set MACH1_MCP_URL and MACH1_API_KEY in your local environment, then run:

npx tsx smoke.ts

Ask an agent about a conversation

Save this as agent.ts. Set MASTRA_MODEL to your enabled provider/model and configure that provider’s API credential in your local environment. Set MACH1_INTERACTION_ID to an admitted conversation.

agent.ts

import { Agent } from "@mastra/core/agent";
import { mcp } from "./client.js";

const task = process.argv.slice(2).join(" ") || "Identify commitments in this conversation and cite the evidence.";
const interactionId = process.env.MACH1_INTERACTION_ID;
const idempotencyKey = process.env.MACH1_IDEMPOTENCY_KEY;

try {
  const tools = await mcp.listTools();
  const agent = new Agent({
    id: "mach1-conversation-analyst",
    name: "Mach-1 conversation analyst",
    instructions: `Use the Mach-1 tools to discover authorized definitions, select or submit the input, poll processing, and cite only findings with evidence. ${interactionId ? `A known interaction ID is ${interactionId}.` : "Discover a relevant authorized interaction or ask for an input."} ${idempotencyKey ? `For a new submission, reuse this caller-generated idempotency key: ${idempotencyKey}.` : "Do not submit until the application supplies MACH1_IDEMPOTENCY_KEY."} Never invent findings or substitute transcript text for evidence.`,
    model: process.env.MASTRA_MODEL || "openai/gpt-5.6-luna",
    tools,
  });
  const result = await agent.generate(task);
  process.stdout.write(`${result.text}\n`);
} finally {
  await mcp.disconnect();
}

npx tsx agent.ts 'Find commitments and cite evidence'

For a new submission, your application must create and persist MACH1_IDEMPOTENCY_KEY before invoking the agent. Reuse the same key and payload after an uncertain result. Keep credentials outside source control.

Contributors with repository access can also run the full schema-check and evaluation harness.

Pass text/turns or an already admitted interaction ID. A local filename alone does not give a remote agent file access; upload or read the file in the application first. MCP submission and results use the same authorized owners as REST. The conversation mach1_* tools include submission, Definition discovery, interaction listing, status, transcript, results and recording. Use the Mach-1 MCP guide for credential boundaries.

Definition discovery returns compact metadata, including the version ID, service, starter marker and output-schema digest. The full schema is available at each output_schema_url; resolve that relative URL against your Mach-1 origin and send the same Bearer key. The REST URL selects the exact published version and rechecks workspace access. This keeps large schemas out of the 64 KiB MCP response while preserving the full schema for applications that need it.

This endpoint performs processing and can incur configured charges. Mintlify’s separate Documentation MCP searches these public docs at the published docs site’s /mcp; it does not submit inputs or charge the Mach-1 ledger.

Forecasting with the same client

A key with forecast permissions also exposes mach1_list_forecast_sources, mach1_submit_forecast, and mach1_get_forecast. The tool inventory follows the key’s current grants. Use forecasting for the request and the agent quickstart for discovery, submission, polling, and pagination.