Skip to main content
By default, aixyz build auto-generates a server from your app/ directory. Create app/server.ts for full control over endpoint registration and middleware. This overrides auto-generation entirely.

​
Full Example

import { AixyzServer } from "aixyz/server";
import { useA2A } from "aixyz/server/adapters/a2a";
import { AixyzMCP } from "aixyz/server/adapters/mcp";

import * as agent from "./agent";
import * as lookup from "./tools/lookup";

const server = new AixyzServer();
await server.initialize();
server.unstable_withIndexPage();

useA2A(server, agent);

const mcp = new AixyzMCP(server);
await mcp.register("lookup", {
  default: lookup.default,
  accepts: { scheme: "exact", price: "$0.001" },
});
await mcp.connect();

export default server;

​
Server Architecture

AixyzServer extends x402ResourceServer from @x402/core/server, which wraps Express 5. This gives you the full Express API alongside built-in x402 payment verification. 
import { AixyzServer } from "aixyz/server";

const server = new AixyzServer();
await server.initialize();

​
Key Properties

  • server.express — the raw Express 5 app
  • server.config — parsed AixyzConfig object

​
unstable_withIndexPage(path?)

Adds a human-readable text page at the specified path (defaults to /) showing agent name, description, version, and skills. 
server.unstable_withIndexPage();
The unstable_withIndexPage() API is experimental and may change in future releases.

​
withX402Exact(route, accepts)

Registers x402 payment middleware on a route: 
server.withX402Exact("POST /agent", {
  scheme: "exact",
  price: "$0.005",
});
The route parameter is a string like "GET /path" or "POST /path".

​
Protocol Adapters

​
useA2A(server, agentExports, taskStore?)

Registers A2A endpoints on the server:
  • GET /.well-known/agent-card.json — agent card generated from aixyz.config.ts
  • POST /agent — JSON-RPC handler (x402-gated if accepts.scheme === "exact")
import { useA2A } from "aixyz/server/adapters/a2a";

// agentExports is `import * as agent from "./agent"`
// It reads both `default` (the agent) and `accepts` (payment config)
useA2A(server, agent);

​
AixyzMCP

Exposes tools to MCP clients at POST /mcp via StreamableHTTPServerTransport: 
import { AixyzMCP } from "aixyz/server/adapters/mcp";

const mcp = new AixyzMCP(server);

// Register tools with payment config
await mcp.register("toolName", {
  default: toolInstance,
  accepts: { scheme: "exact", price: "$0.001" },
});

// Mount the /mcp endpoint
await mcp.connect();
Tools must have an execute function. Payment wrapping is applied if accepts.scheme === "exact".

​
Build Behavior

The build handles server exports differently based on the target:
  • Standalone (aixyz build): The bundled file auto-starts the server. Run directly with bun .aixyz/output/server.js.
  • Vercel (aixyz build --vercel or VERCEL=1): Transforms export default server to export default server.express for Vercel serverless compatibility.

A2A Protocol

Learn about agent cards and JSON-RPC.

MCP Protocol

Expose tools to MCP clients.