Skip to content
AX Framework

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.io

How AX concepts map to MCP

AX conceptMCP primitiveNotes
Capability (action)ToolName, description, input schema
Capability (read)Tool or ResourceUse resources for addressable content
Risk levelTool annotationse.g. readOnlyHint, destructiveHint, idempotentHint
Resource descriptionResourceAddressable by URI
Structured resultTool resultText content, and structured content where supported
GrantTransport-level authorizationMCP 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:

ts
// 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:

ts
// 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.

Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.