MCP integration

Decide what the adapter replaces

Use MCP when an MCP client needs access to the same tools your application already exposes through AGENTO. Reuse the compiled contract instead of maintaining a second set of tool schemas and execution policies.

The adapter gives you handlers, not a listening server. Your MCP SDK integration still owns the transport and caller authentication. First prove the tool with runtime.invoke(); then invoke it through the adapter and compare the structured result.

Example: a booking is still a multi-step operation

Calling the book tool may return needs_selection, then needs_confirmation. These are successful protocol responses describing unfinished business work. Your host must render the choices and approval UI and use the adapter's host continuation methods.

Do not expose confirmation as an ordinary tool for the proposing model to call. Do not report “booked” merely because the MCP call returned without a protocol error. Preserve the AGENTO status and enforce the same user/session binding as your native application.

The examples below assume an existing configured runtime and a request-scoped authenticated caller. Test two callers with distinct sessions to ensure the context callback cannot leak one identity into another request.

AGENTO includes a protocol-independent MCP adapter foundation. It does not ship a complete transport server.

Create the adapter

import { createMcpAdapter } from "agento-runtime";

const handlers = createMcpAdapter(runtime, async () => ({
  sessionId: serverSessionId,
  auth: { token: callerAccessToken },
}));

List tools

const result = await handlers.listTools();

The adapter derives MCP tool metadata from the same compiled registry and adds hints such as read-only, destructive and idempotent behavior.

Call a tool

const result = await handlers.callTool({
  name: "search-services",
  arguments: { q: "hair" },
});

The adapter calls runtime.invoke() with presentation: "raw" and returns the AGENTO result as structured content.

Missing input and continuation states

MCP tool execution may return structured continuation states instead of pretending the tool fully completed:

• needs_input
• needs_selection
• needs_confirmation

Your MCP host/UX must decide how to continue them.

Confirmation is intentionally host-controlled

The adapter provides host methods for confirm() and select(), but confirmation is not published as a generic model-callable tool. This prevents the same model that proposed an effect from granting its own approval.

What the host must provide

The official MCP SDK integration still owns:

• transport initialization;
• protocol negotiation;
• transport authentication;
• request-scoped user identity/context;
• mapping MCP request lifecycle to a server-owned AGENTO session.

Never derive credentials or session ownership from model-supplied tool arguments.