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 MCPPlugin, serving tools at /mcp over a stateless WebStandardStreamableHTTPServerTransport.

​
Endpoints

EndpointMethodDescription
/mcpPOSTJSON-RPC requests using WebStandardStreamableHTTPServerTransport
/mcpGETSSE stream for server-initiated messages
/mcpDELETESession termination (stateless, returns 200)

​
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 MCPPlugin:
app/server.ts
import { MCPPlugin } from "aixyz/app/plugins/mcp";
import * as lookup from "./tools/lookup";

// Register tools and mount the /mcp endpoint
await server.withPlugin(
  new MCPPlugin([
    {
      name: "lookup",
      exports: {
        default: lookup.default,
        accepts: { scheme: "exact", price: "$0.001" },
      },
    },
  ]),
);

​
Session Integration

Paid MCP tools automatically get session context. When a tool is invoked with x402 payment, getSession() returns the payer-scoped session inside the tool handler — no additional configuration needed. 
import { getSession } from "aixyz/app/plugins/session";

// Inside an MCP tool handler:
const session = getSession();
await session?.set("key", "value"); // stored per-payer
See SessionPlugin for the full API.

​
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 server.withPlugin(
  new MCPPlugin([
    {
      name: "premiumSearch",
      exports: {
        default: searchTool,
        accepts: { scheme: "exact", price: "$0.001" },
      },
    },
  ]),
);

Tools

How tools are defined in the app/ directory.

SessionPlugin

Payer-scoped storage for MCP tools.

A2A Protocol

Agent discovery and communication via A2A.