Skip to content

ADR-0022: MCP as the tool, resource and prompt protocol

Decision

This page records a decision and its status. A Proposed decision is not binding; an Accepted decision is binding on the Factory until amended or superseded.

  • Status: Accepted 2026-10-09 by the product owner (decision D44)
  • Date: 2026-10-09
  • Deciders: Dmitry Khaymov (product owner); proposed by the 2026-10 design plan
  • Tags: mcp, tools, governance, protocols

Context

The 2025 pages treated MCP as an optional side channel. Since then MCP has become the common protocol for exposing tools, resources and prompts to agents across vendors, with HTTP (streamable) and stdio transports, OAuth 2.1 protected-resource authorization, and registry and governance practice. ConnectSoft already ships ConnectSoft.Extensions.ModelContextProtocol (hosting, OAuth protected-resource metadata, Microsoft Agent Governance Toolkit integration with policy paths, fail-closed and audit options), but the agent host maps its MCP endpoint unauthenticated by default and anonymous callers are governed under a shared identity.

Decision

  1. Protocol: every tool, resource and prompt capability the Factory consumes or exposes is an MCP capability. Native in-process tools are wrapped as MCP-compatible descriptors so that the executor sees one shape.
  2. One governed path: all tool calls, whether from a Factory agent, an IDE client or a partner agent, pass the governed executor (GW-05, BC-08): scope, policy decision, side-effect class, approval binding (D21), idempotency key, receipt, audit.
  3. Descriptors: every MCP tool carries a descriptor in the tool registry: id, version, JSON schema, side-effect class (read, sandbox, shared-write, external, production, publication, spend), authorization and secret requirements, timeout, retry, rate limits, audit requirements, health. The side-effect class is declared by the tool owner and validated against the policy of the calling agent (the generator enforces this in the model).
  4. Servers: MCP servers are registered in the MCP server registry (McpServerRegistryService, BC-08) with transport, authentication, governance policy and the tools they expose; authentication is on by default for any server reachable beyond the local process; anonymous access is a documented exception per server.
  5. Resources and prompts: MCP resources map to knowledge sources with scope and classification; MCP prompts map to skills or workflow steps, never to policy.
  6. Clients: the Factory consumes external MCP servers only through connections (BC-16) with credential references from the secret broker; a client never holds a raw secret.
  7. Agents as tools: exposing an agent as an MCP tool (the agents framework supports it) is allowed only through the lifecycle pipeline, never by calling the raw agent (closes the bypass found on 2026-10-08).

Consequences

  • Positive: one tool model for native, MCP and partner capabilities; IDE clients (VS Code, Claude Code, Cursor) connect to the same governed surface; governance toolkit and audit apply uniformly.
  • Negative: the agent host template must change its MCP defaults; every existing tool needs a descriptor with a side-effect class; MCP server registration is new work.
  • Neutral: A2A (ADR-0023) covers agent-to-agent calls; MCP stays the tool protocol.

Alternatives considered

Alternative Why not chosen
Proprietary tool interface with MCP adapters at the edge Loses interoperability with IDE clients and partner servers; duplicates descriptors
MCP unauthenticated inside the cluster A tool path without identity cannot carry scope or approval binding

Evidence

  • ConnectSoft.Extensions.ModelContextProtocol options (McpAuthorizationOptions.Enabled default false; McpGovernanceOptions); agent template appsettings.json EnableMcpToolExposure: true; verification record V-A rows of 2026-10-08.