Tools & MCP Platform — aggregate roots¶

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

Aggregate	Service	Root entity	Events	Tables
McpServer	McpServerRegistryService	McpServer	McpServerRegistered, McpServerStateChanged, McpCapabilitiesDiscovered	McpServers, McpToolBindings, McpResourceBindings, McpPromptBindings
ToolDescriptor	ToolAdapterService	ToolDescriptor	ToolDescriptorActivated, ToolDescriptorRetired	ToolDescriptors
ToolInvocation	ToolAdapterService	ToolInvocation	ToolInvoked, ToolInvocationDenied, ToolEffectUncertain, SandboxLeased, SandboxReleased	ToolInvocations, SandboxLeases

McpServer (McpServerRegistryService)¶

One registered MCP server with its direction, transport, endpoint or connection, authentication, governance policy, discovered capabilities and health.

Field	Type	Required	Description
`serverId`	`string`	yes
`tenantId`	`string`	yes
`name`	`string`	yes
`direction`	`enum:McpDirection`	yes
`transport`	`enum:McpTransport`	yes
`endpointRef`	`string`	no	For consumed HTTP servers a connection reference (BC-16); credentials brokered.
`commandRef`	`string`	no	For stdio servers the sandboxed command and image.
`authentication`	`enum:McpAuthentication`	yes
`governancePolicyRef`	`string`	yes	Policy bundle applied to every call through this server (Microsoft Agent Governance Toolkit integration).
`protocolVersion`	`string`	yes
`state`	`enum:McpServerState`	yes
`releaseId`	`string`	no	Published asset release when the server is a Factory asset.
`lastHandshakeAt`	`datetime`	no
`version`	`long`	yes

Invariants

A server reachable beyond the local process is Active only with authentication OAuth2ProtectedResource or WorkloadIdentity; NoneException requires a recorded Platform-admin approval and an expiry.
Discovered tools become callable only when bound to a tool descriptor with a declared side-effect class; an unbound tool is listed but not invocable.
Resources map to knowledge sources with scope and classification; prompts map to skills or workflow steps, never to policy (ADR-0022 §5).
A consumed server's credentials come from a connection and the Secret Broker; the registry never stores a secret.

States (McpServerState)

stateDiagram-v2
    Registered --> Verified : HandshakeAndDiscoverySucceeded
    Verified --> Active : BindingsApproved
    Active --> Degraded : HandshakeFailed
    Degraded --> Active : HandshakeRecovered
    Active --> Retired : Retire
    Degraded --> Retired : Retire

Hold "Alt" / "Option" to enable pan & zoom

Entities: McpToolBinding, McpResourceBinding, McpPromptBinding · Value objects: —

ToolDescriptor (ToolAdapterService)¶

Runtime read model of a Published tool asset — identifier, version, JSON schema, description, side-effect and risk class, authorization and secret requirements, timeout, retry, rate limits, audit requirements, health, kind and server binding.

Field	Type	Required	Description
`toolId`	`string`	yes
`version`	`string`	yes
`releaseId`	`string`	yes	Published asset release (BC-04).
`tenantId`	`string`	yes
`kind`	`enum:ToolKind`	yes
`schemaRef`	`string`	yes	JSON schema of input and output (tool-invocation-v1 envelope).
`sideEffectClass`	`string`	yes	read
`riskClass`	`enum:RiskClass`	yes
`authorization`	`json`	yes	Scopes and roles required of the caller.
`secretDependencies`	`list:string`	yes	Connection or secret references brokered at call time.
`timeoutSeconds`	`int`	yes
`retryPolicy`	`json`	yes
`rateLimits`	`json`	yes
`auditRequirements`	`json`	yes	What the receipt must capture (arguments hash, outputs hash, command line…).
`sandboxKind`	`enum:SandboxKind`	yes
`mcpServerId`	`string`	no
`healthy`	`bool`	yes
`active`	`bool`	yes

Invariants

A descriptor is usable only while its release is Published and the descriptor is healthy; deprecation and revocation deactivate it with the release's in-flight policy.
The side-effect class is declared by the tool owner at publication and validated against the policy of every agent that lists the tool (model rule D21); the executor never lowers it, the environment class may raise it.
Shell tools carry an allow-list and a block-list of command patterns; a command matching the block-list (terraform destroy, az group delete, kubectl delete namespace, DROP DATABASE, rm -rf …) is Denied or escalated to production class per policy.

ToolInvocation (ToolAdapterService)¶

One tool call from reception to receipt — scope, tool version, request hash, idempotency key, effective side-effect class, policy decision, approval binding, sandbox lease, execution, sanitized result reference, receipt and audit reference.

Field	Type	Required	Description
`invocationId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	yes
`environmentId`	`string`	no
`runId`	`guid`	no
`attemptId`	`guid`	no
`fencingToken`	`long`	no
`callerKind`	`string`	yes	agent
`toolId`	`string`	yes
`toolVersion`	`string`	yes
`requestHash`	`hash`	yes
`idempotencyKey`	`string`	yes
`declaredClass`	`string`	yes
`effectiveClass`	`string`	yes	Declared class raised by the environment class (Production) or policy.
`policyDecisionId`	`guid`	no
`approvalId`	`guid`	no
`state`	`enum:InvocationState`	yes
`sandboxLeaseId`	`guid`	no
`resultRef`	`string`	no	Artifact reference of the sanitized result.
`resultHash`	`hash`	no
`receiptRef`	`string`	no	tool-invocation-v1 receipt artifact.
`auditRef`	`string`	no
`failureClass`	`string`	no	transient
`startedAt`	`datetime`	yes
`endedAt`	`datetime`	no

Invariants

The pipeline order is fixed: schema validation → agent permission → tenant policy → side-effect classification → approval if required → credential broker → sandbox → execute → result sanitization → audit; no stage may be skipped.
Gated classes (shared-write, external, production, publication, spend above threshold) execute only with an approval bound to this invocation's request hash and the exact tool version; a different hash is a new approval (D21).
The same idempotency key within scope returns the existing receipt; a call is never executed twice for one key.
A call whose effect cannot be confirmed (lost sandbox, timeout after side effect, host loss) ends Uncertain, is reported to the runtime as such and is never retried automatically.
Results are sanitized before they reach a model (secrets stripped, size bounded, provenance tagged as tool-result, instructions in results treated as data).

States (InvocationState)

stateDiagram-v2
    Received --> Validated : SchemaValid
    Received --> Denied : SchemaInvalidOrToolInactive
    Validated --> Authorized : PermissionAndPolicyPassed
    Validated --> Denied : PolicyDenied
    Authorized --> AwaitingApproval : GatedClassWithoutApproval
    AwaitingApproval --> Brokered : ApprovalBound
    AwaitingApproval --> Denied : ApprovalRejectedOrExpired
    Authorized --> Brokered : CredentialsAndSandboxLeased
    Brokered --> Executing : Started
    Executing --> Observed : ResultObserved
    Executing --> Failed : ErrorBeforeEffect
    Executing --> Uncertain : EffectUnconfirmed
    Executing --> Cancelled : InterruptedBeforeEffect

Hold "Alt" / "Option" to enable pan & zoom

Entities: SandboxLease · Value objects: —