reflexr.mcp¶

The mcp extra. See External agents over MCP.

An MCP server, so external agents can publish into, read and operate workspaces.

Every tool that changes something goes through reflexr.workspace.Workspaces.execute, the handler REST and the WebSocket use, once per command_id, so it behaves the same whichever way it arrives.

The server¶

ReflexrMcp ¶

ReflexrMcp(
    workspaces: Workspaces,
    *,
    resolve: ResolveClient,
    authorize: Authorize | None = None,
    name: str = "reflexr",
    bus: SubscriptionBus | None = None,
)

An MCP server over reflexr workspaces.

Mount http_app in the application, and run lifespan in the application's lifespan. Every tool that changes something goes through Workspaces.execute, as REST and the WebSocket do, attributed to the client's ExternalAgentActor.

The MCP SDK traces each request itself; the server adds the tenant, workspace and actor to those spans. Building the SDK's server configures logging for the whole process; this server undoes that, so logging stays the application's.

Parameters:

Name	Type	Description	Default
`workspaces`	`Workspaces`	Opens tenant-scoped workspaces, holds the rules, and carries out every tool's command, once per `command_id`, so a retry is safe, as on REST. The tools that install, update and archive stored rules are served only if it has `stored_rules`.	required
`resolve`	`ResolveClient`	Authenticates each request.	required
`authorize`	`Authorize \| None`	Whether a client may use a workspace of its tenant, asked on every tool call, resource read and resource subscription that names a workspace; allows everything if omitted. A refusal is a tool error, or a failed resource read or subscription, carrying the `forbidden` rejection's message.	`None`
`name`	`str`	The server's name.	`'reflexr'`
`bus`	`SubscriptionBus \| None`	Where resource-change notifications go; in-process by default.	`None`

http_app ¶

http_app(**options: Any) -> Starlette

Return the Streamable HTTP app to mount, e.g. at /mcp.

lifespan `async` ¶

lifespan() -> AsyncGenerator[None]

Run the HTTP session manager; stop watching workspaces afterwards.

aclose `async` ¶

aclose() -> None

Stop the tasks that turn run facts into resource notifications.

ResolveClient `module-attribute` ¶

ResolveClient = Callable[
    [McpContext],
    Awaitable[tuple[TenantId, ExternalAgentActor]],
]

Authenticates an MCP request: returns the client's tenant and actor.

McpContext ¶

McpContext = Context[Any, Request]

The context a ResolveClient receives: the MCP SDK's Context of one request.

Over HTTP, ctx.request_context.request is the Starlette Request the call arrived in, so an authenticator written for the router's HTTPConnection can take it once it is checked for None, which it is in process, as in tests. ctx.headers holds its headers.

run_uri ¶

run_uri(
    tenant_id: TenantId,
    workspace_id: WorkspaceId,
    run_id: str,
) -> str

Return a run's resource URI.

INSTRUCTIONS `module-attribute` ¶

INSTRUCTIONS = "This server is a set of event logs, one per workspace, watched by rules that run agents and workflows. Publish events to trigger them, read the log to see what happened, and operate runs and rules. Events you publish are attributed to you. Give each change a command_id of your own, and the same one if you retry it, so that it is made once."