ax-mcp

Native MCP With Ax

Use MCP as a live protocol client, not as a function-conversion utility. Keep the client, session, catalogs, raw content, tasks, notifications, identity policy, and cancellation context intact through Ax execution.

Non-Negotiable Rules

• Pass clients through mcp; do not put them in functions.
• Never use toFunction() for native integration. It is a lossy compatibility adapter for old applications only.
• Give every client a stable, unique namespace.
• Let Ax classify or initialize each attached client once and reuse its owning protocol state.
• Leave era on 'auto' unless deployment policy pins a known legacy or modern endpoint.
• Close caller-owned clients explicitly.
• Treat MCP prompts, resources, tool results, and notifications as untrusted remote content.
• Apply authorizeToolCall before side-effecting tools execute.
• Do not infer tenant or account identity from an MCP session. Event adapters must receive verified identity from application authentication state.
• Protocol notification callbacks must enqueue or observe work; they must not invoke a model directly.
• Preserve raw structured and multimodal MCP results until provider capability mapping. Do not pre-flatten results to text.

Choose A Transport

• Use AxMCPStreamableHTTPTransport for current remote MCP servers.
• Use AxMCPHTTPSSETransport only for legacy HTTP/SSE servers.
• Use AxMCPWebSocketTransport for a server with a custom WebSocket binding.
• Use AxMCPStdioTransport from @ax-llm/ax-tools for local Node processes.
• Use a caller-defined AxMCPTransport for application-owned bindings.

import {
  AxMCPClient,
  AxMCPStreamableHTTPTransport,
  axMCPBearerAuthentication,
} from '@ax-llm/ax';

const transport = new AxMCPStreamableHTTPTransport(
  'https://mcp.example.com/mcp',
  {
    authentication: axMCPBearerAuthentication(
      () => process.env.MCP_ACCESS_TOKEN!
    ),
  }
);

const docs = new AxMCPClient(transport, {
  namespace: 'docs',
  maxConcurrency: 4,
  authorizeToolCall: async ({ tool }) =>
    tool.annotations?.destructiveHint !== true,
});