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

# MCP Protocol

> Model Context Protocol support for sharing tools with MCP clients

## Overview

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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.

<Note>Files starting with `_` (e.g., `app/tools/_helpers.ts`) are excluded from tool registration.</Note>

## Manual Setup

If you're using a custom server, wire up MCP manually with the `MCPPlugin`:

```typescript title="app/server.ts" theme={null}
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.

```typescript theme={null}
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](/api-reference/session-plugin) for the full API.

## Payment-Gated Tools

Tools with `accepts.scheme === "exact"` require [x402 payment](/protocols/x402) via `@x402/mcp`. The payment wrapper is applied automatically when you provide an `accepts` configuration during registration.

```typescript theme={null}
// This tool requires $0.001 per invocation
await server.withPlugin(
  new MCPPlugin([
    {
      name: "premiumSearch",
      exports: {
        default: searchTool,
        accepts: { scheme: "exact", price: "$0.001" },
      },
    },
  ]),
);
```

<CardGroup cols={2}>
  <Card title="Tools" icon="folder-tree" href="/api-reference/tools">
    How tools are defined in the app/ directory.
  </Card>

  <Card title="SessionPlugin" icon="database" href="/api-reference/session-plugin">
    Payer-scoped storage for MCP tools.
  </Card>

  <Card title="A2A Protocol" icon="diagram-project" href="/protocols/a2a">
    Agent discovery and communication via A2A.
  </Card>
</CardGroup>