Table of Contents

Orleans.Lattice.Api.Mcp

A Model Context Protocol (MCP) server for Orleans.Lattice - it exposes a running lattice cluster's transport-agnostic API facades as MCP tools an AI agent can discover and drive over a standard, authenticated MCP endpoint.

What is it?

Orleans.Lattice.Api.Mcp is the agent-facing control surface of a lattice cluster. The core library is a data plane reached through grain interfaces; the Orleans.Lattice.Api.* packages add transport-agnostic facades over the read state, the read/write data path, the backup control plane, the authorization admin plane, runtime replication control, whole-tree administration, and tenant administration. This package binds those same facades onto the official ModelContextProtocol C# SDK, so a language-model agent talks to the cluster the same way it talks to any other MCP server - no bespoke client, no hand-rolled schema.

It is built from four parts:

  • A front door. AddLatticeMcp(...) registers the MCP server, the streamable-HTTP transport, a fail-closed authorizer seam, and the credential bridge; MapLatticeMcp() maps the endpoint. The server starts with no tools - each tool module is opt-in.
  • Permission-scoped discovery. A per-session configurator computes the tool list from the authenticated caller's effective permissions and adds a lattice_capabilities meta-tool. A facade group's tools are listed only to a caller holding an Allow grant for an operation the group covers, so a caller never sees a group it holds no grant for, and a mutating data tool is listed only to a caller whose grants include a mutating data-plane operation; within a listed group, each call is still authorized per tree and per verb by the facade's access gate.
  • Built-in tool modules. AddStateTools(), AddDataTools(), AddBackupTools(), AddAuthTools(), AddReplicationTools(), and AddTreeAdminTools() each register a group of thin adapters over the matching facade, named lattice_<group>_<verb>; a tenancy-enabled cluster additionally exposes the tenant self-awareness and tenant-admin modules (AddTenantSelfAwarenessTools() and AddTenantAdminTools()). Destructive verbs (writes, backup control, auth administration, replication control, schema management, tree lifecycle/control, and tenant lifecycle operations) are opt-in. Every built-in module is served under both the in-silo and remote topologies, less the few tools the remote host defers because their gRPC method is not yet bound (see Deferred tools).
  • In-silo or remote hosting. Co-host the server on a silo that exposes the facades in-process, or run it out-of-silo with AddLatticeMcpRemote(...), which binds the same tool modules over the Orleans.Lattice.Api.*.Grpc clients to front a cluster it is not co-located with.

Core properties

  • Fail-closed by construction. The default DenyAllMcpAuthorizer, the fail-closed credential bridge, and RequireAuthorization (default true) mean an unauthenticated session is default-denied: it can enumerate nothing and call nothing until the host opts in with a real authorizer and authenticator.
  • No parallel logic. Every tool is a thin adapter that delegates to the matching Orleans.Lattice.Api.* facade - the same facade the gRPC bindings adapt - and re-implements none of its behaviour, so the MCP surface stays in lock-step with the rest of the API family. The state, auth, and tree-administration tools mostly return the facade's own records; the data, backup, replication, and tenant tools return compact MCP result records projected from the facade's answer (for example with values base64-encoded).
  • Permission-scoped, coarse discovery. Discovery filters the tool list to the caller's effective permissions before it is returned, so an agent never sees the tools of a facade group it holds no grant for. The filter is coarse - one Allow grant for any operation a group covers lists the group - with two refinements: the scopeless Telemetry and AppInstall capabilities count only when granted cluster-wide, and the data group lists its mutating tools only to a caller holding a mutating data-plane grant, so a read-only caller is offered only the data reads. The facade's access gate therefore still refuses, per call, a verb, a tree, or a Deny rule the caller's grants do not cover.
  • Opt-in and least-privilege. The server ships no tools; each module is added explicitly, and within a module the destructive verbs stay hidden until the host enables them (enableWrites, enableControl, enableAdministration, enableSchemaControl, enableLifecycle).
  • Credential flow-through. The credential bridge lifts the authenticated MCP session identity onto the ambient LatticeCredentialContext, so per-tree / per-key enforcement runs through the same access gate the gRPC bindings and the data path already use. The binding adds no authorization path of its own.
  • OAuth discovery (opt-in). Advertise OAuth 2.0 Protected Resource Metadata (RFC 9728) so a spec-compliant MCP client can discover the authorization server and run the sign-in flow itself instead of needing a pre-pasted token. See Setup.

Quick start

Co-host the MCP server on an existing Orleans.Lattice silo. Register the facades the tool modules need, add the MCP front door and an authorizer, add the tool modules to expose, then map the endpoint:

var builder = WebApplication.CreateBuilder();

builder.Host.UseOrleans(silo =>
{
    silo
        .AddLattice((s, storageName) => s.AddMemoryGrainStorage(storageName))
        .AddLatticeStateApi()
        .AddLatticeDataApi();
});

// The MCP front door. The default authorizer denies every facade tool whether
// or not RequireAuthorization is on, so register a real one before serving.
builder.Services.AddLatticeMcp(o => o.RequireAuthorization = true);
builder.Services.AddSingleton<ILatticeApiMcpAuthorizer, AllowAllMcpAuthorizer>();

// Opt in to the tool modules. Reads are always exposed; writes stay off here.
builder.Services.AddStateTools();
builder.Services.AddDataTools(enableWrites: false);

var app = builder.Build();
app.MapLatticeMcp();

Permission-scoped discovery reads each caller's grants through the auth facade, so a deployment also registers AddLatticeAuth(...) and AddLatticeAuthApi() on the silo (the minimal snippet above omits them); without the auth facade, discovery grants no group and an authenticated caller is offered only lattice_capabilities (see Setup). An MCP client then connects to the mapped endpoint, calls lattice_capabilities to see which facade groups its credential unlocks (the session's tool list is itself already scoped to the caller's grants), and invokes tools such as lattice_state_list_trees, lattice_data_get, or lattice_data_read_range.

For a co-hosted silo that serves the MCP endpoint, see the McpServer sample under samples/. As written it registers no ILatticeApiMcpAuthorizer, so the default DenyAllMcpAuthorizer leaves its agent with only lattice_capabilities - its README describes the missing registration.

Reference

  • Setup - registering the front door, the options, and mapping the endpoint.
  • Tools - the built-in tool modules, their opt-in flags, and the full tool catalogue.
  • Security - the fail-closed posture, the authorizer seam, the credential bridge, and permission-scoped discovery.
  • Remote hosting - running the server out-of-silo over the gRPC clients with AddLatticeMcpRemote(...).

See also