--- title: "Orleans.Lattice.Api.Mcp" url: "https://nsta1.github.io/Orleans.Lattice/docs/lattice.api.mcp/README.html" source: "https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/docs/lattice.api.mcp/README.md" package: "Orleans.Lattice.Api.Mcp" version: "9.9.0" documents: "Orleans.Lattice 9.9.0 (release line 9.9)" built: "2026-10-04" all-pages: "https://nsta1.github.io/Orleans.Lattice/llms.txt" bundle: "https://nsta1.github.io/Orleans.Lattice/docs/lattice.api.mcp/llms-full.txt" --- # Orleans.Lattice.Api.Mcp Part of the [documentation map](../index.md). A Model Context Protocol (MCP) server for [Orleans.Lattice](../../README.md) - 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`](https://www.nuget.org/packages/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__`; 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](remote.md#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](https://www.rfc-editor.org/rfc/rfc9728)) 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](setup.md#oauth-discovery-rfc-9728). ## 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: ```csharp verify 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(); // 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](setup.md#prerequisites)). 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`](../../samples/McpServer/README.md) sample under [`samples/`](https://github.com/NSTA1/Orleans.Lattice/tree/release/9.9/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](setup.md) - registering the front door, the options, and mapping the endpoint. - [Tools](tools.md) - the built-in tool modules, their opt-in flags, and the full tool catalogue. - [Security](security.md) - the fail-closed posture, the authorizer seam, the credential bridge, and permission-scoped discovery. - [Remote hosting](remote.md) - running the server out-of-silo over the gRPC clients with `AddLatticeMcpRemote(...)`. ## See also - [`Orleans.Lattice.Api.State`](../lattice.api.state/README.md) - the read-only state facade the state tools adapt. - [`Orleans.Lattice.Api.Data`](../lattice.api.data/README.md) - the read/write data facade the data tools adapt. - [`Orleans.Lattice.Api.Backup`](../lattice.api.backup/README.md) - the backup control facade the backup tools adapt. - [`Orleans.Lattice.Api.Auth`](../lattice.api.auth/README.md) - the authorization admin facade the auth tools adapt. - [`Orleans.Lattice.Api.Replication`](../lattice.api.replication/README.md) - the replication control facade the replication tools adapt. - [`Orleans.Lattice.Api.TreeAdmin`](../lattice.api.treeadmin/README.md) - the whole-tree administration facade (composing the schema control facade) the tree-administration tools adapt. - [`Orleans.Lattice.Api.TenantAdmin`](../lattice.api.tenantadmin/README.md) - the tenant-administration, region-residency, and self-service facades the tenant tools adapt. - [`Orleans.Lattice.Api.Mcp.Telemetry`](../lattice.api.mcp.telemetry/README.md) - the opt-in telemetry tool module that serves cluster metrics over this server. - [`Orleans.Lattice.Api.Mcp.RepoContext`](../lattice.api.mcp.repocontext/README.md) - the opt-in repository-context tool module that serves durable codebase context as `repocontext_*` tools over this server. - [`Orleans.Lattice.Api.Mcp.Apps`](../lattice.api.mcp.apps/README.md) - the opt-in surface that adds every enabled [installable app](../lattice.apps/README.md)'s tools to this endpoint, namespaced `{slug}_{tool}`, without changing the facade groups or `lattice_capabilities`.