McpServerRegistryService

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-08 Tool Execution
Platform / plane	Tools & MCP Platform / Capability & Tools
Deployment granularity	module of host · host ToolExecutorHost
Status	target · ConnectSoft.Factory.Tools.Mcp
Built from	connectsoft-microservice · libraries: connectsoft-extensions-model-context-protocol, connectsoft-extensions-saas-abstractions, connectsoft-extensions-messaging-model, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-audit-net
Decisions	ADR-0022, ADR-0015
Traceability	FR-02 FR-05 FUX-02 NFR-02 NFR-13 XL-02 XL-10

Purpose and responsibilities

ADR-0022 makes MCP the protocol for every tool, resource and prompt the Factory consumes or exposes. McpServerRegistryService is where servers are registered with their direction (consumed or exposed), transport (streamable HTTP or sandboxed stdio), endpoint or connection, authentication (OAuth 2.1 protected resource or workload identity; "none" only as a recorded, expiring exception), governance policy bundle and protocol version. After a handshake it discovers tools, resources and prompts and keeps their bindings: tools bind to Published tool descriptors with a declared side-effect class, resources map to knowledge sources with classification, prompts map to skills or workflow steps and never to policy. An unbound tool is listed but not callable.

Context and boundaries

flowchart LR
    S["McpServerRegistryService"]
    ToolAdapterService["ToolAdapterService"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| IntegrationService["IntegrationService"]
    S -->|grpc| SecretBrokerService["SecretBrokerService"]
    S -->|grpc| PolicyEngineService["PolicyEngineService"]
    S -->|event| AgentRegistryService["AgentRegistryService"]
    S -. "McpServerRegistered" .-> E_McpServerRegistered(("event"))
    S -. "McpServerStateChanged" .-> E_McpServerStateChanged(("event"))
    S -. "McpCapabilitiesDiscovered" .-> E_McpCapabilitiesDiscovered(("event"))

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

Domain model

McpServer — One registered MCP server with its direction, transport, endpoint or connection, authentication, governance policy, discovered capabilities and health. (catalog entry)

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.

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

Events: McpServerRegistered, McpServerStateChanged, McpCapabilitiesDiscovered · Tables: McpServers, McpToolBindings, McpResourceBindings, McpPromptBindings · Repository: McpServerRepository

erDiagram
    McpServer {
        string serverId PK
        string tenantId
        string name
        enum_McpDirection direction
        enum_McpTransport transport
        string endpointRef
        string commandRef
        enum_McpAuthentication authentication
        string governancePolicyRef
        string protocolVersion
        enum_McpServerState state
        string releaseId
        datetime lastHandshakeAt
        long version
    }
    McpToolBinding {
        string toolName

        hash schemaHash

        string toolId

        string toolVersion

        string declaredClass

        bool bound

    }
    McpResourceBinding {
        string resourceUri

        guid sourceId

        string classification

    }
    McpPromptBinding {
        string promptName

        string skillId

        string workflowStepRef

    }
    McpServer ||--o{ McpToolBinding : contains
    McpServer ||--o{ McpResourceBinding : contains
    McpServer ||--o{ McpPromptBinding : contains

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

stateDiagram-v2
    [*] --> Registered
    Registered --> Verified: handshake and discovery succeeded
    Verified --> Active: bindings approved (publication-class action)
    Active --> Degraded: handshake failed
    Degraded --> Active: handshake recovered
    Active --> Retired
    Degraded --> Retired
    Retired --> [*]

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

Entities and value objects

McpToolBinding (entity, in McpServer) — A tool the server exposes bound to a Factory tool descriptor.

Field	Type	Required	Description
toolName	string	yes
schemaHash	hash	yes
toolId	string	no
toolVersion	string	no
declaredClass	string	no
bound	bool	yes

McpResourceBinding (entity, in McpServer) — A resource the server exposes mapped to a knowledge source.

Field	Type	Required	Description
resourceUri	string	yes
sourceId	guid	no
classification	string	yes

McpPromptBinding (entity, in McpServer) — A prompt the server exposes mapped to a skill or workflow step.

Field	Type	Required	Description
promptName	string	yes
skillId	string	no
workflowStepRef	string	no

Data model and storage

Store	Role	Engine / profile	Tables
Tool execution store	primary	azure-sql / nhibernate-sqlserver	McpServers, McpToolBindings, McpResourceBindings, McpPromptBindings

Table	Owner	Columns	Indexes
dbo.McpServers	McpServer	14	1
dbo.McpToolBindings	McpToolBinding	8	0
dbo.McpResourceBindings	McpResourceBinding	5	0
dbo.McpPromptBindings	McpPromptBinding	5	0

Full DDL: appendix.

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/mcp-servers	ListMcpServers	factory.tools.read	read	natural	GW-03	Registered servers with direction, transport, authentication, state and binding counts.
POST	/factory/mcp-servers	RegisterMcpServer	factory.tools.admin	shared-write	key-header	GW-03	Register a server (Asset maintainer or Platform admin); credentials by connection reference only.
POST	/factory/mcp-servers/{serverId}/discover	DiscoverMcpCapabilities	factory.tools.admin	sandbox	key-header	GW-03	Handshake and list tools, resources and prompts into bindings (sandbox action).
POST	/factory/mcp-servers/{serverId}/activate	ActivateMcpServer	factory.tools.admin	publication	natural	GW-03	Approve bindings and activate the server (publication-class action; NoneException authentication needs the recorded exception).
GET	/factory/mcp-servers/{serverId}/capabilities	GetMcpCapabilities	factory.tools.read	read	natural	GW-03	Tools, resources and prompts with their bindings.
POST	/factory/mcp-servers/{serverId}/retire	RetireMcpServer	factory.tools.admin	publication	natural	GW-03	Retire a server; its descriptors become unhealthy and inactive.

gRPC service	Method	Streaming	Visibility	Side effects	Summary
McpRegistry	ResolveTool	none	internal	read	Resolve a tool id to its server, transport, binding and authentication for the executor.
McpRegistry	ListCapabilities	none	internal	read	Capabilities visible to a scope (for IDE clients connecting to the exposed server).

Messages

Event	Topic	Scope / v	Aggregate	Consumers	Summary
McpServerRegistered	tool-execution.mcp-servers.v1.mcp-server-registered	integration / 1	McpServer	StudioBff, AuditService	A server was registered.
McpServerStateChanged	tool-execution.mcp-servers.v1.mcp-server-state-changed	integration / 1	McpServer	ToolAdapterService, StudioBff, DashboardService, AuditService	Verified, active, degraded or retired.
McpCapabilitiesDiscovered	tool-execution.mcp-servers.v1.mcp-capabilities-discovered	integration / 1	McpServer	StudioBff, DashboardService	Tools, resources and prompts were discovered and bindings refreshed.

McpServerRegistered payload:

Field	Type	Required	Description
serverId	string	yes
tenantId	string	yes
direction	enum:McpDirection	yes
transport	enum:McpTransport	yes
authentication	enum:McpAuthentication	yes

McpServerStateChanged payload:

Field	Type	Required	Description
serverId	string	yes
tenantId	string	yes
fromState	enum:McpServerState	yes
toState	enum:McpServerState	yes

McpCapabilitiesDiscovered payload:

Field	Type	Required	Description
serverId	string	yes
tenantId	string	yes
tools	int	yes
resources	int	yes
prompts	int	yes
unbound	int	yes

Command	Handled by	Result events	Summary
RegisterMcpServer	McpServer	McpServerRegistered
DiscoverMcpCapabilities	McpServer	McpCapabilitiesDiscovered, McpServerStateChanged
ActivateMcpServer	McpServer	McpServerStateChanged

Event	Producer	Handler	Purpose
AssetReleasePublished	AgentRegistryService	RegisterPublishedServer	Register and verify MCP servers published as Factory assets.
AssetReleaseRevoked	AgentRegistryService	RetirePublishedServer	Retire revoked server assets.

Workers and jobs

Worker	Trigger	Output events	Retry	Idempotency key	Summary
HandshakeProbe	schedule */5 * * * *	McpServerStateChanged	fixed	serverId + probeWindow	Performs the MCP initialize handshake against every Active server and tracks protocol version and health.
CapabilityDiscovery	event	McpCapabilitiesDiscovered	exponential	serverId + capabilityHash	Lists tools, resources and prompts after registration or on schema change and refreshes bindings; new or changed schemas unbind until re-approved.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Tools:McpRegistry	HandshakeTimeoutSeconds	int	10	yes	no	Handshake timeout.
Tools:McpRegistry	AllowNoneAuthenticationExceptions	bool	false	no	no	Whether NoneException registrations are accepted at all in this installation.

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.tools.mcp_servers	updown	{server}	tenant, direction, state, authentication	Servers by state and authentication.
connectsoft.factory.tools.mcp_handshakes	counter	{handshake}	server, outcome	Handshake outcomes.
connectsoft.factory.tools.mcp_unbound_tools	updown	{tool}	tenant	Discovered tools without a descriptor binding.

Security

Authentication	client-credentials
Scopes	factory.tools.read (Read servers and capabilities.); factory.tools.admin (Register, discover, activate, retire.)
Roles	AssetMaintainer, Operator, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	internal
Max side-effect class	publication
Secrets	—

A changed tool schema on a consumed server unbinds the tool until an Asset maintainer re-approves it, so a server cannot silently widen what an agent may do. Consumed servers' credentials are connection references brokered per handshake; the registry stores no secret.

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
IntegrationService	grpc	Connections for consumed HTTP servers.	fail-fast	yes
SecretBrokerService	grpc	Credentials for handshakes and discovery.	fail-fast	yes
PolicyEngineService	grpc	Governance policy bundles and exception approvals.	fail-fast	yes
AgentRegistryService	event	Server and tool assets.	queue	yes

Inbound

Target	Kind	Purpose	Failure mode	Required
ToolAdapterService	grpc	ResolveTool per invocation.	—	yes
StudioBff	sync-http	Server administration views.	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Server schema changed	capability hash differs	affected bindings unbound until re-approved; calls to them Denied with reason	none	0
Handshake fails repeatedly	probe outcomes	Degraded; executor marks its descriptors unhealthy	none	30

NFR targets

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment

Granularity	module of host · host ToolExecutorHost
Topologies	saas-default, hybrid, on-prem, hybrid-compute
Runtime	—; replicas —–—
Ports	—

Current implementation

ConnectSoft.Extensions.ModelContextProtocol hosts MCP servers and integrates the governance toolkit; no registry, discovery, binding or handshake health exists; the AgentKit .ai registry of earlier experiments is reference input only (D19). See MCP.

Later capabilities

Cross-organization MCP registry federation and discovery (technology radar: assess); marketplace listing of certified servers (PF-07); automatic binding proposals from schema similarity.

Decisions and traceability

Family	Ids
FR	FR-02, FR-05
FUX	FUX-02
NFR	NFR-02, NFR-13
XL	XL-02, XL-10

Related

• MCP · ToolAdapterService · ADR-0022 · Integration platform

• Tools & MCP Platform microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map