Gateway tools and MCP tools

What it isCopy Anchor Link

A Gateway tool is a Module's command or query offered to a model as a tool. Each call the model makes runs as an Operation through the Module's Gateway, continuing the Operation Context of the run that offered the tool. Validation, the authorizers and, for a command, its own Unit of Work apply to each call.

An MCP tool is a tool of an MCP server the Host's AI options name, offered to a model beside its Gateway tools. The call runs on that server, never as an Operation, and the Host, not the run, owns the server's client.

When to use itCopy Anchor Link

• A model needs to read or change your data: give its run a Gateway tool over a command or query of the Module, and the call runs through the same pipeline as any other Operation.
• A model needs a capability another program provides: name that program's MCP server in the Host's AI options and give the run its tools.

The Proving Sample's agent, Catalog's AskAboutProducts command, gives its model one Gateway tool, GetProduct.

How it worksCopy Anchor Link

Tool on a Module's IGatewayProcessor<TModule> makes a command or query a Gateway tool for one run's Operation Context. The model's arguments are read into a record, whose schema the model is given, and mapped explicitly to the operation:

var getProduct = catalog.Tool(
    "GetProduct",
    "Finds one product of the catalog by its id: its id, its category's id and its name.",
    context,
    (ProductToFind product) => new GetProductQuery(product.ProductId)
);

A run inside an authorized Operation, as in this command's handler, gives each call a trusted continuation, so a permission the operation declares is not checked again: give such a run only tools its Operation may run. A run outside one, with a context your code builds, gives untrusted continuations, and each call's permissions are checked for the Actor.

A failed Result goes back to the model as a failed tool result with its Errors, never as an exception, so the model can recover. An MCP server's tools are listed with IMcpServers.ListToolsAsync and given to the run beside its Gateway tools.

What the Kit guaranteesCopy Anchor Link

Failure messagesCopy Anchor Link

Next stepsCopy Anchor Link