MCP Protocol

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

Endpoint	Method	Description
`/mcp`	POST	JSON-RPC requests using `WebStandardStreamableHTTPServerTransport`
`/mcp`	GET	SSE stream for server-initiated messages
`/mcp`	DELETE	Session 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.

Getting Started

CLI

Config

File-system layout

Functions

Protocols

MCP Protocol

Overview

Endpoints

Compatible Clients

Automatic Registration

Manual Setup

Session Integration

Payment-Gated Tools

Tools

SessionPlugin

A2A Protocol

​Overview

​Endpoints

​Compatible Clients

​Automatic Registration

​Manual Setup

​Session Integration

​Payment-Gated Tools

Tools

SessionPlugin

A2A Protocol

Overview

Endpoints

Compatible Clients

Automatic Registration

Manual Setup

Session Integration

Payment-Gated Tools