Tools & MCP Platform — APIs

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.

McpServerRegistryService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

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 (code-first, internal)

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).

ToolAdapterService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/tools	ListTools	factory.tools.read	read	natural	GW-03	Active tool descriptors visible to the caller with side-effect and risk class, kind, server and health.
GET	/factory/tools/{toolId}	GetTool	factory.tools.read	read	natural	GW-03	A descriptor with schema, authorization, secret dependencies, limits and audit requirements.
POST	/factory/tools/{toolId}/dry-run	DryRunTool	factory.tools.read	sandbox	natural	GW-03	Validate arguments and show the pipeline outcome (class, policy, approval needed, sandbox kind) without executing.
GET	/factory/runs/{runId}/tool-receipts	ListRunToolReceipts	factory.runs.read	read	natural	GW-03	Tool receipts of a run: tool, version, effective class, decision, approval, outcome, hashes.
GET	/factory/tool-invocations/{invocationId}	GetToolInvocation	factory.runs.read	read	natural	GW-03	One invocation with its pipeline stages, sandbox lease and receipt.
POST	/factory/tool-invocations/{invocationId}/confirm-effect	ConfirmToolEffect	factory.tools.operate	shared-write	natural	GW-03	An operator confirms or denies that an Uncertain invocation's effect happened, from the receipt and external evidence.

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
ToolExecutor	Invoke	server	internal	production	Execute a tool call for an attempt (fencing token), IDE client or partner caller through the full pipeline; streams progress for long tools and ends with the receipt (tool-invocation-v1).
ToolExecutor	Validate	none	internal	read	Schema validation and pipeline preview without execution.
ToolExecutor	Interrupt	none	internal	shared-write	Stop an executing invocation (cancellation); the effect is settled as observed, cancelled or uncertain.

ToolExecutorHost

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/tools/health	ToolsHealth	factory.health.read	read	natural	GW-01	Liveness, readiness and dependency health (store, policy engine, secret broker, sandbox capacity, registered MCP servers).
GET	/tools/meta/capabilities	ToolsCapabilities	factory.meta.read	read	natural	GW-03	Executor capabilities: transports (MCP streamable HTTP, stdio bridge, native), sandbox kinds available, supported descriptor schema versions.