> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioncx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://build.aioncx.com/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:

```bash theme={"system"}
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.

```typescript client.ts theme={"system"}
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:

```typescript smoke.ts theme={"system"}
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:

```bash theme={"system"}
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.

```typescript agent.ts theme={"system"}
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();
}
```

```bash theme={"system"}
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](https://github.com/Xaqt/atlas/tree/main/examples/mach1-mastra).

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](https://docs.aioncx.com/integrations/mcp.md) 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](https://docs.aioncx.com/mach1/forecasting.md) for the request and the [agent quickstart](https://docs.aioncx.com/agents/quickstart.md) for discovery, submission, polling, and pagination.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.