Implementation
MCP Integration
Exposing AX capabilities through the Model Context Protocol.
The Model Context Protocol (MCP) is an open protocol for connecting AI applications to external tools, resources, and prompts. It was introduced by Anthropic in 2024 and is supported by a growing number of AI clients. If agents reach your product through MCP-capable applications, an MCP server is a natural delivery channel for your AX layer.
Open protocol · modelcontextprotocol.ioHow AX concepts map to MCP
| AX concept | MCP primitive | Notes |
|---|---|---|
| Capability (action) | Tool | Name, description, input schema |
| Capability (read) | Tool or Resource | Use resources for addressable content |
| Risk level | Tool annotations | e.g. readOnlyHint, destructiveHint, idempotentHint |
| Resource description | Resource | Addressable by URI |
| Structured result | Tool result | Text content, and structured content where supported |
| Grant | Transport-level authorization | MCP specifies OAuth-based authorization for HTTP transports |
MCP does not define approvals, receipts, or an error vocabulary. Carry those in your tool results using the same shapes as your HTTP API.
Registering actions as tools
If your actions are defined as contracts, registration is a loop:
// mcp/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { actions } from "@/lib/actions";
import { execute } from "@/lib/ax/execute";
export function createServer(ctxFor: (extra: unknown) => Promise<ActionContext>) {
const server = new McpServer({ name: "northwind", version: "2026.10.1" });
for (const action of Object.values(actions)) {
server.registerTool(
action.name,
{
description: action.description,
inputSchema: action.input.shape,
annotations: {
readOnlyHint: action.risk === "read",
destructiveHint: action.risk === "high",
idempotentHint: Boolean(action.idempotent),
},
},
async (args, extra) => {
const result = await execute(action, args, await ctxFor(extra));
return {
content: [{ type: "text", text: JSON.stringify(result) }],
isError: result.status === "failed",
};
},
);
}
return server;
}Writing tool descriptions
Tool descriptions are read by a model choosing which tool to call. They should be precise about scope and side effects:
// Weak
description: "Orders tool";
// Strong
description:
"Place an order for the current cart using a saved payment method. " +
"Charges the customer. Orders above the customer's limit return approval_required " +
"and must be resumed with the approvalId after the customer approves.";Approvals over MCP
When a tool returns approval_required, the agent should relay the approval summary to the person. The approval itself should still happen through a channel the product controls, such as a notification or a link, so the decision is attributable and cannot be asserted by the agent. The agent then calls the tool again with the approvalId.
Security considerations
- Authorize every tool call against the caller's grant. Tool annotations are hints for clients, not security controls.
- Treat tool arguments as untrusted input, exactly like HTTP request bodies.
- Do not return content from third parties (reviews, messages) in a way that could be confused with instructions.
- Rate-limit per grant.
Related
Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.