Skip to main content

​
Overview

The Model Context Protocol (MCP) allows AI clients to discover and invoke tools exposed by your agent. aixyz implements MCP via the AixyzMCP class, serving tools at /mcp over a stateless StreamableHTTPServerTransport.

​
Endpoint

EndpointMethodDescription
/mcpPOSTMCP tool endpoint using StreamableHTTPServerTransport

​
Compatible Clients

Any MCP-compatible client can connect to your agent’s /mcp endpoint:
  • Claude Desktop
  • VS Code (GitHub Copilot)
  • Cursor
  • Other MCP-enabled tools
Point the client at your agent’s MCP URL: 
http://localhost:3000/mcp

​
Automatic Registration

When using the standard app/ directory structure, all tools in app/tools/*.ts are automatically registered as MCP tools during the build. No additional configuration is needed.
Files starting with _ (e.g., app/tools/_helpers.ts) are excluded from tool registration.

​
Manual Setup

If you’re using a custom server, wire up MCP manually with the AixyzMCP class: 
import { AixyzMCP } from "aixyz/server/adapters/mcp";
import * as lookup from "./tools/lookup";

const mcp = new AixyzMCP(server);

// Register tools — each gets a name and its exports
await mcp.register("lookup", {
  default: lookup.default,
  accepts: { scheme: "exact", price: "$0.001" },
});

// Mount the /mcp endpoint
await mcp.connect();

​
Payment-Gated Tools

Tools with accepts.scheme === "exact" require x402 payment via @x402/mcp. The payment wrapper is applied automatically when you provide an accepts configuration during registration. 
// This tool requires $0.001 per invocation
await mcp.register("premiumSearch", {
  default: searchTool,
  accepts: { scheme: "exact", price: "$0.001" },
});

Agent Structure

How tools are defined in the app/ directory.

A2A Protocol

Agent discovery and communication via A2A.