AIFACTORY-FEAT-098: Model Context Protocol library: authenticated by default¶
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.
A design artefact, not a tracker
This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).
Epic Ecosystem component extensions · Increment I0 Readiness · State elaborated · Route backend-developer · Phase before development · Build order 4 of 185 (Templates and libraries)
Before development
Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I0 are developed. The mark travels with every task (tag phase:before-development).
The Model Context Protocol library authenticates every server and client call by default and passes the caller's scope to the governed tool executor, so that no tool path bypasses policy. Component: Extensions.ModelContextProtocol (extend).
| Delivers | — |
| Stubs | — |
| Realizes | components: cmp-mcp |
| Requirements | — |
| Depends on | — |
| Sources | model/components.yaml, docs/architecture/ecosystem-composition.md |
AIFACTORY-US-198: Model Context Protocol library: an HTTP server requires authorization by default and anonymous exposure is a declared exception¶
enabling · persona platform-admin
As a platform admin, I want a server built with the Model Context Protocol library to require authorization as soon as it is reachable beyond the local process, so that no host exposes its tools anonymously because a setting was left at its default.
The Features page of ConnectSoft.Extensions.ModelContextProtocol describes two transports, Stdio and Http, and an authorization options class with OAuth 2.0, protected resource metadata, and authority and audience validation of the token; the source of that class, McpAuthorizationOptions, states that Enabled is off by default and that the server then accepts unauthenticated requests, and docs/planes/capability-tools/mcp.md records the same default and that the agent host maps its endpoint without authorization. ADR-0022 decision 4 makes authentication on by default for any server reachable beyond the local process and anonymous access a documented exception per server. This PBI changes the default of the library. On the Http transport Enabled is true unless the host declares an anonymous exception that carries a reason. The existing rule of the options class stays: ResourceUri and AuthorizationServers are required when Enabled is true, because the pointer to the protected resource metadata cannot be served without them. A host on the Http transport therefore has three outcomes at start. It configures ResourceUri and AuthorizationServers, leaves Enabled unset or sets it, and runs protected. It declares the anonymous exception with its reason and runs open, with the exception logged at start and reported in the health data of the server, so that the server registry can record it. Or it does neither and fails options validation with ResourceUri and AuthorizationServers named. Switching Enabled off without a declared exception fails the start as well. On a protected server a call without a token, with an expired token or with a token for another audience is answered 401 with the pointer to the protected resource metadata, no tool handler runs and the refusal is counted. The Stdio transport, which never leaves the local process, keeps its behaviour. A host that relied on the earlier default fails at start with the setting named instead of running open.
Acceptance criteria
| AC1 | Given a host that registers a server on the Http transport, configures ResourceUri and AuthorizationServers of McpAuthorizationOptions and leaves Enabled unset, when a client calls a tool without a token, then the call is answered 401 with the pointer to the protected resource metadata, no tool handler runs and the refusal is counted, because authorization is on by default as ADR-0022 decision 4 requires. |
| AC2 | Given a host whose Http server has authorization switched off, when the host starts, then options validation fails with the setting named unless an anonymous exception with a reason is declared; an Http host that has neither ResourceUri and AuthorizationServers nor a declared anonymous exception fails at start with ResourceUri and AuthorizationServers named, because the existing rule that requires them when authorization is enabled stays; a declared exception is logged at start and reported in the health data of the server, which is the documented exception per server of ADR-0022 decision 4 (docs/planes/capability-tools/mcp.md). |
| AC3 | Given a token issued for another audience or an expired token, when a tool is called over Http, then the call is refused with 401 and no handler runs; a server on the Stdio transport keeps accepting its local client without a token, and tests cover both transports (ADR-0022 decision 4). |
| Traces: adrs | ADR-0022 |
| Sources | model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0022-mcp-as-tool-protocol.md, docs/planes/capability-tools/mcp.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-163 Authentication and scope on MCP calls by default |
implementation | The authorization options of the library are on by default for the Http transport: on a host that configures ResourceUri and AuthorizationServers and leaves Enabled unset, an unauthenticated call, an expired token and a token for another audience are refused with 401 and the pointer to the protected resource metadata, no tool handler runs and the refusal is counted; an authenticated call reaches the handler with the tenant and project scope that AIFACTORY-US-199 binds. |
ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-978 Start validation of an Http server and the declared anonymous exception |
implementation | The server options validator fails the start of a host whose Http server has authorization off and no anonymous exception, and of an Http host that has neither ResourceUri and AuthorizationServers nor a declared exception, with the missing settings named; the RequiredIf rule of McpAuthorizationOptions on the two settings stays; the exception setting carries a reason, is logged at start and is reported in the health data of the server; the Stdio transport is exempt. |
ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-979 Test host and token fixtures for the authorization default |
fixture | A test host on the Http transport, configured with ResourceUri and AuthorizationServers and with Enabled unset, and a local token issuer that produces a valid token, an expired token and a token for another audience; a second host runs on the Stdio transport; both are reused by the scope tests of the next PBI. |
ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-980 Verify the authorization default on both transports |
verification | Run dotnet test -c Release --no-build on the library solution; the tests of the unauthenticated call, the wrong audience, the start validation with authorization off, the start refusal of an Http host with no authorization setting and the Stdio transport pass and prove AC1 to AC3 of AIFACTORY-US-198 (ADR-0022). |
ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-US-199: Model Context Protocol library: the scope of the authenticated caller reaches every tool handler and the governance layer¶
enabling · persona platform-admin
As a platform admin, I want the tenant, the project and the agent identity of the authenticated caller to be available to every tool handler and to the governance layer of the library, so that the governed tool executor decides and records every tool call under the scope of its caller and no tool path bypasses policy.
ADR-0022 decision 2 sends every tool call, from a Factory agent, an IDE client or a partner agent, through the governed executor with scope, policy decision, side-effect class, idempotency key, receipt and audit, and ADR-0015 decision 2 takes the tenant and the project of a Factory contract from the authenticated context, never from prompt text or a caller-controlled header. The library validates a token today but hands nothing of it to a tool: its governance options carry a default agent id used as a fallback and a switch that requires an authenticated agent identity, which is off by default, as docs/planes/capability-tools/mcp.md records. This PBI binds the scope. After authorization the library exposes a scope accessor to the tool handler and to the governance layer with the tenant id, the project id, the agent or user identity and, where the token carries them, the run, step and attempt identity. A token without a tenant claim is answered 401 and a token with a tenant and without a project 403, both before the handler runs; these are the codes the Factory profile of the base template answers for the same token, so two backends of one estate do not differ. A tenant or project named in a tool argument or in a header is never used as the scope. The library recognises a scope argument by a stated rule: a tool parameter is a scope argument when the tool declares it so, through a scope attribute of the library on the parameter or an entry of its tool descriptor, or when it carries the canonical name tenantId or projectId; any other parameter, a free-text one included, is not inspected. A scope argument recognised by this rule that contradicts the scope of the token is refused before the handler with a typed tool error whose reason is scope-mismatch, as decision D114 settles: the token itself is valid, so the refusal is a result of the tool call that the caller can classify and not a 401 or 403, no handler runs and the refusal is counted. This is the fail-closed rule for conflicting evidence. With authorization on, the governance layer requires the authenticated agent identity by default and the fallback agent id is not applied. The scope is added to the activity of the tool invocation and to the audit record of the governance decision. The library hands the executor the scope and never the raw token of the caller, which the tools page calls unsafe to forward.
Acceptance criteria
| AC1 | Given an authenticated call whose token carries a tenant and a project, when a tool handler runs, then the scope accessor returns the tenant id, the project id and the caller identity of the token, with the run, step and attempt identity where the token carries them, and the governance decision of the call is recorded with the same scope (ADR-0022 decision 2, ADR-0015 decision 2). |
| AC2 | Given a token without a tenant claim, a token with a tenant and without a project, or a call whose scope argument (a parameter the tool declares as scope, or one named tenantId or projectId) names a tenant or a project other than that of the token, when the tool is called, then the call is refused before the handler runs, with 401 for the missing tenant claim, 403 for the missing project and a typed tool error whose reason is scope-mismatch for the contradicting scope argument, and the scope is never taken from an argument or a header; an undeclared free-text parameter is not inspected, and a test with two tenants proves that a handler never observes the scope of another caller (ADR-0015 decision 2; its amendment keeps 403 for a missing scope inside the tenant). |
| AC3 | Given a server with authorization on, when the governance layer evaluates a call, then the authenticated agent identity is required by default and the fallback agent id of the options is not applied; the raw token of the caller is not available to the handler and is not forwarded, as docs/planes/capability-tools/mcp.md requires of tool credentials (ADR-0022 decision 2). |
| Traces: adrs | ADR-0015, ADR-0022 |
| Depends on | AIFACTORY-US-198 |
| Sources | model/components.yaml, docs/architecture/adr/0022-mcp-as-tool-protocol.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/capability-tools/mcp.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-981 Scope accessor from the validated token for tool handlers |
implementation | A request-scoped accessor of the library returns tenant id, project id, caller identity and the optional run, step and attempt identity read from the validated token; the claim names are options with the canonical names as defaults; a token without a tenant claim is answered 401 and a token with a tenant and without a project 403, both before the handler. A tool parameter is a scope argument when the tool declares it so, through a scope attribute of the library on the parameter or an entry of its tool descriptor, or when it carries the canonical name tenantId or projectId; a scope argument that contradicts the scope of the token is refused before the handler with a typed tool error whose reason is scope-mismatch, the refusal is counted, and no other parameter is inspected. |
ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-982 Authenticated agent identity required by the governance layer by default |
implementation | With authorization on, the governance options require the authenticated agent identity by default and ignore the fallback agent id; the governance decision, its audit record and the activity of the tool invocation carry the scope of the caller; the raw token is not exposed to handlers. | ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-983 Sample tool and two-tenant tokens for the scope tests |
fixture | A sample tool in the test project returns the scope it observes, a second sample tool has a declared scope parameter and a third an undeclared free-text parameter that is not checked; tokens of two tenants and of two projects of one tenant call them through the test host of AIFACTORY-TASK-979, including a token without a tenant claim, a token without a project, a call whose declared scope argument contradicts the token and a call whose free-text parameter names another tenant and is handled. | ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-984 Verify that every handler runs under the scope of its caller |
verification | Run dotnet test -c Release --no-build on the library solution; the two-tenant tests, the 401 for a missing tenant claim, the 403 for a missing project, the contradicting scope argument refused with the typed tool error scope-mismatch, the unchecked free-text parameter and the governance identity test pass and prove AC1 to AC3 of AIFACTORY-US-199 (ADR-0015, ADR-0022). |
ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-US-200: Model Context Protocol library: a client call to a server beyond the local process carries a token obtained through a credential port¶
enabling · persona platform-admin
As a platform admin, I want the client side of the library to authenticate every call to a remote server with a token it obtains through a credential port, so that no host holds a raw secret for an MCP server and no caller token is forwarded to one.
The feature asks that the library authenticates every server and every client call by default. The pages of ConnectSoft.Extensions.ModelContextProtocol describe the hosting of a server only; a host that consumes a remote server builds its client by hand. ADR-0022 decision 6 lets the Factory consume an external server only through a connection with a credential reference from the secret broker, and states that a client never holds a raw secret; docs/planes/capability-tools/mcp.md adds that forwarding the token of a caller to a downstream server is unsafe and that a token must be scoped to the resource it is presented to. This PBI adds a client registration to the library. A client for a server on the Http transport is registered with the address of the server and a credential reference, never with a secret value; before each call the client asks a credential port for a token whose audience is that server and presents it. Registration of a remote server without a credential reference fails at start with the server named, unless the same kind of declared anonymous exception as on the server side is set. The client never reuses the token of the incoming request. A server that answers 401 ends the call with a failure the caller can classify, and the response body is not logged. A client for a Stdio server of the local process needs no credential. The credential port is an abstraction of the library; its implementation over the secret broker belongs to the service that owns connections in a later increment.
Acceptance criteria
| AC1 | Given a client registered for a server on the Http transport with a credential reference, when a tool of that server is called, then the client obtains a token for the audience of that server through the credential port and presents it, and the options of the client hold a reference and never a secret value, as ADR-0022 decision 6 requires. |
| AC2 | Given the registration of a remote server without a credential reference and without a declared anonymous exception, when the host starts, then start fails with the server named; a client for a Stdio server of the local process starts without a credential (ADR-0022 decision 4 and decision 6). |
| AC3 | Given a call that arrives at a host with the token of its caller, when the host calls a downstream server through the client, then the token of the caller is never forwarded and the downstream call carries only the token obtained for that server; a downstream 401 ends the call with a classified failure and nothing of the response body is logged (docs/planes/capability-tools/mcp.md, ADR-0022 decision 6). |
| Traces: adrs | ADR-0022 |
| Depends on | AIFACTORY-US-198 |
| Sources | model/components.yaml, docs/architecture/adr/0022-mcp-as-tool-protocol.md, docs/planes/capability-tools/mcp.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-985 Credential port and client options with a credential reference |
contract | The library defines a credential port that returns a token for a named server and audience, and client options that carry the server address, the transport and a credential reference; the options type has no member for a secret value and its validator names a remote server that has no reference. | ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-986 Client registration that obtains a token per call and never forwards the caller token |
implementation | A registration extension of the library builds a client for a registered server; on the Http transport it asks the credential port for a token before each call and presents it, it never reads the token of the incoming request, and a 401 of the server ends the call with a classified failure without logging the response body. | ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-987 Fake credential port and a protected test server for the client tests |
fixture | A fake credential port issues tokens per audience and records each request; the protected test host of AIFACTORY-TASK-979 acts as the remote server and records the token it receives, so that a test can assert which token arrived. | ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-988 Verify the authenticated client call and the start refusal |
verification | Run dotnet test -c Release --no-build on the library solution; the tests of the token per call, the start refusal without a credential reference and the absence of a forwarded caller token pass and prove AC1 to AC3 of AIFACTORY-US-200 (ADR-0022). |
ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-US-201: Model Context Protocol library: the package is built, tested and published to the ConnectSoft feed with the version the consumers pin¶
evidence · persona platform-admin
As a platform admin, I want proof that the library with the authorization default is on the ConnectSoft feed with a version a consumer can pin, so that every host that maps an MCP endpoint is protected by restoring that version.
This PBI is the publication proof of the feature. The library is consumed by the agent host template, by the worker template for its operations tools and by the AI skills library template, and docs/planes/capability-tools/mcp.md records that the agent host maps its endpoint without authorization on the version it pins today. The pipeline of the library builds, tests, packs and pushes the package to the ConnectSoft feed, the Azure Artifacts feed the ConnectSoft libraries already publish to, which decision D114 makes the Factory feed; the publication stage runs only when the tests pass and refuses a version that is already on the feed. A probe proves the change from the side of a consumer: a clean host that has the ConnectSoft feed as its only source restores the published version, configures the authorization servers and the resource of an Http server, leaves Enabled at its default, and a call without a token is refused; a second probe host that still switches authorization off without a declared exception fails at start; a third probe host that maps an Http server with no authorization setting at all fails at start with ResourceUri and AuthorizationServers named. The pages of the library state the new defaults and carry a migration note for a host that relied on anonymous access: declare the exception with its reason or configure ResourceUri and AuthorizationServers. The published version is recorded in the Runbook page, where the consuming templates read their pin. A host on an earlier version is not protected by this feature; moving the pins is work of the features that own those templates.
Acceptance criteria
| AC1 | Given the pipeline of the library repository, when it runs after the work of the feature, then the package is built, tested, packed and pushed to the ConnectSoft feed, the publication stage runs only after the tests pass and refuses a version that is already on the feed, and the published version is recorded in the Runbook page of the library (ADR-0028, model/backlog/epics.yaml). |
| AC2 | Given clean probe hosts with the ConnectSoft feed as their only package source, when the first restores the published version, configures ResourceUri and AuthorizationServers and leaves Enabled at its default, then a call without a token is refused with 401; when the second switches authorization off without a declared exception and the third maps an Http server with no authorization setting at all, then each fails at start with the setting named, which is the default ADR-0022 decision 4 requires. |
| AC3 | Given the pages of the library, when a maintainer of a consuming host reads them, then the Features page states authorization on by default, the scope accessor and the client credential port, and a migration note explains the declared anonymous exception with its reason, which is the documented exception per server of ADR-0022 decision 4. |
| Traces: adrs | ADR-0022, ADR-0028 |
| Depends on | AIFACTORY-US-198, AIFACTORY-US-199, AIFACTORY-US-200 |
| Sources | model/components.yaml, model/backlog/epics.yaml, docs/architecture/ecosystem-composition.md, docs/planes/capability-tools/mcp.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-989 Publication stage with the version guard in the library pipeline |
operations | The pipeline of the library pushes the package to the ConnectSoft feed after the tests pass; a version already on the feed is refused with the reason and the run fails; the published version is written to the Runbook page. | ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-990 Feed probe hosts for the published package |
fixture | Three probe hosts with the ConnectSoft feed as their only source restore the published version: the first configures the authority and the resource (AuthorizationServers and ResourceUri), leaves Enabled at its default and refuses a call without a token with 401; the second switches authorization off without an exception and fails at start; the third maps an Http server with no authorization setting and fails at start with ResourceUri and AuthorizationServers named; all three run as the last stage of the pipeline. |
ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-991 Library pages state the new defaults and the migration note |
documentation | The Features, Getting Started and Runbook pages of the library describe authorization on by default, the declared anonymous exception, the scope accessor, the typed tool error scope-mismatch for a contradicting scope argument, the required agent identity and the client credential port, with a migration note for a host that relied on anonymous access. |
ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-TASK-992 Verify the published package by the probe hosts |
verification | One pipeline run publishes the package and the three probe hosts behave as stated; a rerun with the same version is refused; the runs prove AC1 to AC3 of AIFACTORY-US-201 (ADR-0022, ADR-0028). | ConnectSoft.Extensions.ModelContextProtocol |
AIFACTORY-US-098: Model Context Protocol library: authenticated by default is delivered and proven by its consumers¶
enabling · persona platform-admin
As a platform admin, I want Extensions.ModelContextProtocol to carry authenticated by default, so that it serves MCP hosting and governance without later rework.
This is the integration PBI of the feature. A platform admin takes the Model Context Protocol library from a server that accepts anonymous calls by default to a published package in which an Http server requires authorization unless an exception is declared, every tool handler and the governance layer run under the tenant, the project and the identity of the authenticated caller, and a client call to a remote server carries a token obtained through a credential port. The implementation lives in the earlier PBIs of this file; this PBI proves them together. An unauthenticated call is refused and no tool runs, an authenticated call reaches the handler with its scope, a token without a tenant claim is answered 401 and a token without a project 403, a scope argument that contradicts the token is refused with the typed tool error scope-mismatch, and the package is on the ConnectSoft feed with a recorded version. The feature is done when no tool path of a host built on the published version bypasses authorization and scope, which is what the governed executor of ADR-0022 needs from the library. Repository of the feature: ConnectSoft.Extensions.ModelContextProtocol. The services that reach the library in a later increment are the agent runtime, the server registry and the tool adapter.
Acceptance criteria
| AC1 | Given the library repository ConnectSoft.Extensions.ModelContextProtocol, when its pipeline runs, then the package builds, its tests pass and it publishes to the ConnectSoft feed with a verified version that the consuming repositories pin (ADR-0028, model/components.yaml). |
| AC2 | Given the work of AIFACTORY-TASK-163 (authentication and scope on MCP calls by default) is done, then an unauthenticated MCP call is refused and an authenticated one reaches the tool handler with tenant and project scope, as ADR-0022 decision 2 and decision 4 require. |
| AC3 | Given a host built on the published version, when its tools are called with a token of one tenant and then of another, then each handler observes only the scope of its caller, a token without a tenant claim is answered 401 and a token without a project 403, and a client call to a remote server carries a token from the credential port and never the token of the caller (ADR-0015 decision 2, ADR-0022 decision 6). |
| AC4 | Given the documentation site after the delivery, when docs/planes/capability-tools/mcp.md is read, then it describes authorization on by default for the Http transport, the declared anonymous exception, the scope handed to tool handlers and the client credential port, and no longer states the earlier defaults as the current state (ADR-0022). |
| Traces: adrs | ADR-0015, ADR-0022, ADR-0028 |
| Depends on | AIFACTORY-US-198, AIFACTORY-US-199, AIFACTORY-US-200, AIFACTORY-US-201 |
| Sources | model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0022-mcp-as-tool-protocol.md, docs/planes/capability-tools/mcp.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-993 Tools page of the documentation site revised to the delivered defaults |
documentation | docs/planes/capability-tools/mcp.md describes the library with authorization on by default for the Http transport, the declared anonymous exception, the scope handed to tool handlers and the client credential port, and no longer states the earlier defaults as the current state. | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-685 Verify mcp-delivered by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build on the library solution and the probe hosts against the published version; they pass and prove AC1 to AC3 of AIFACTORY-US-098, and the revised page of AIFACTORY-TASK-993 proves AC4. |
ConnectSoft.Extensions.ModelContextProtocol |