@@ -10,7 +10,7 @@ Metadata-protocol: added
 An `mcp` instance's `include` decides which tools it exposes. Until now nothing noticed when the server rewrote one of them, for example a new description that steers an agent or an `inputSchema` that asks for more than it did. `providerConfig.toolsSnapshot` is a record of tool name → the sha256 of that tool's definition. It is keyed by tool name, like `include`, and the two compose.
 
 - **The digest.** sha256, lowercase hex, of the UTF-8 canonical JSON of `{ name, description, inputSchema }` from the tool's `tools/list` entry. A member the server does not send is left out. Canonical JSON sorts object keys in UTF-16 code-unit order at every depth, keeps array order, writes primitives as `JSON.stringify` does and has no whitespace: the RFC 8785 (JCS) form for values read from JSON. `computeMcpToolsSnapshot(tools)` and `mcpToolDigest(tool)` are exported and are the functions the check uses.
-- **The check.** On every materialization each pinned tool is hashed and compared on its own. A pinned tool served with a different description or `inputSchema`, or no longer served, degrades the instance: the provider throws `ConnectorUpstreamChangedError` (`CONNECTOR_UPSTREAM_CHANGED`), not the upstream-unavailable marker, so the logs say the pin did not match rather than that the server is down. Its reason names each such tool and the digest the server now serves, and none of the instance's tools are exposed. The instance is re-checked on the retry backoff and recovers once the server serves the pinned definitions again. An edited pin re-materializes it at once. A pinned tool that `include` also lists is reported by the pin when the server stops serving it, not as an `include` typo.
+- **The check.** On every materialization each pinned tool is hashed and compared on its own. A pinned tool served with a different description or `inputSchema`, or no longer served, degrades the instance: the provider throws `ConnectorUpstreamChangedError` (`CONNECTOR_UPSTREAM_CHANGED`), not the upstream-unavailable marker, so the logs say the pin did not match rather than that the server is down. Its reason names each such tool and the digest the server now serves, and none of the instance's tools are exposed. The instance is re-checked on the retry backoff and recovers once the server serves the pinned definitions again. An edited pin re-materializes it at once. A pinned tool that `include` also lists is reported by the pin when the server stops serving it, not as an `include` typo. When the instance's own credential reached the server (its `auth` over http), a pinned tool the server does not list takes the credential path instead (`ConnectorCredentialRejectedError`, 403, both causes named, a stored credential marked `rejected`), since the server may list only the tools that credential may use; a served pinned tool that hashes differently is still `CONNECTOR_UPSTREAM_CHANGED`.
 - **Refused before connecting.** A `toolsSnapshot` that is not a record of tool name → 64 lowercase hex characters fails the boot, and so does a pin on a tool `include` leaves out, since that pin would never be checked.
 - Without `toolsSnapshot`, an instance behaves exactly as before. A tool the pin does not name is not checked.
 - `McpConnectorOptions.include` now also receives the tool's `tools/list` entry as a second argument. An existing one-argument predicate is unaffected.
@@ -319,7 +319,11 @@ On every materialization each pinned tool is hashed and compared on its own:
   change, review it and set the pin to the served digest (the edit
   re-materializes the instance at once). This holds for a pinned tool
   `include` also lists: once pinned, a tool the server stops serving is
-  reported by the pin, not as an `include` typo.
+  reported by the pin, not as an `include` typo. When the instance's own
+  credential reached the server (its `auth` over http), a pinned tool the
+  server does not list may be one hidden from that credential, so it is
+  degraded as a credential the upstream refuses instead, naming both causes —
+  a served tool that hashes differently is still reported by the pin.
 - A tool the pin does not name is not checked. Pin every tool you depend on,
   and keep tools the server adds out with `include`.
 
 
@@ -333,7 +333,11 @@ async function credentialRejectionStatus(err: unknown): Promise<number | undefin
  * {@link toolsSnapshotDriftError}). A
  * pinned name's absence is the pin's to report even when `include` lists it
  * too: the pin says the tool existed with that definition, so its absence is
- * the server's change rather than a typo.
+ * the server's change rather than a typo — unless the instance's credential
+ * reached the server, which may hide a tool from that credential: then a
+ * missing pinned tool takes the credential path ({@link ConnectorCredentialRejectedError},
+ * both causes named), and only a served tool that hashes differently is
+ * {@link ConnectorUpstreamChangedError}.
  */
 export function createMcpProviderFactory(deps: McpProviderDeps = {}): ConnectorProviderFactory {
   return async (ctx) => {
@@ -517,10 +521,14 @@ export function createMcpProviderFactory(deps: McpProviderDeps = {}): ConnectorP
       // without the tool the author listed (a typo, a tool the server renamed
       // or dropped, or one hidden from this credential), and the first sign
       // would be a flow failing at run time.
-      // A pinned entry is left to the pin below: its absence is the server's
-      // change, reported with the pin's other findings, not a typo.
+      // A pinned entry is left to the pin below — its absence is the server's
+      // change, reported with the pin's other findings, not a typo — but only
+      // when no instance credential reached the server. When one did, a
+      // missing pinned entry may be a tool hidden from that credential, which
+      // the answer cannot tell apart from a dropped one, so it takes the
+      // credential's path below like any other entry (#27401 contract review).
       const offered = new Set(listedTools);
-      const pinned = new Set(snapshot ? Object.keys(snapshot) : []);
+      const pinned = new Set(snapshot && !credentialSent ? Object.keys(snapshot) : []);
       const unknown = [...new Set(includeList)].filter((entry) => !offered.has(entry) && !pinned.has(entry));
       if (unknown.length > 0) {
         await bundle.close().catch(() => {});
@@ -574,6 +582,16 @@ export function createMcpProviderFactory(deps: McpProviderDeps = {}): ConnectorP
       const drift = compareToolsSnapshot(snapshot, selectedTools);
       if (drift) {
         await bundle.close().catch(() => {});
+        // A pinned tool the server does not list, on an instance whose
+        // credential reached it (a pin with no `include`; an included one was
+        // refused above), is the credential's or the server's change, and the
+        // answer cannot say which — so it takes the credential's path, as an
+        // `include` entry does: degraded naming both causes, a stored
+        // credential marked `rejected`, no retry against the same value. A
+        // served tool that hashes differently is the server's change alone.
+        if (credentialSent && drift.missing.length > 0) {
+          throw pinnedToolsHiddenError(ctx.name, drift.missing, listedTools);
+        }
         throw toolsSnapshotDriftError(ctx.name, drift);
       }
     }
@@ -616,12 +634,41 @@ function toolsSnapshotDriftError(connectorName: string, drift: ToolsSnapshotDrif
   const more = findings.length > named.length ? `; … ${findings.length - named.length} more` : '';
   return new ConnectorUpstreamChangedError(
     `connector-mcp provider: connector '${connectorName}' providerConfig.toolsSnapshot does not match the tools ` +
-      `its MCP server serves: ${named.join('; ')}${more}. None of the instance's tools are exposed while a pinned ` +
-      `tool differs. If the change is expected, review it and set each pin to the digest the server now serves; ` +
+      `its MCP server serves: ${named.join('; ')}${more}. This materialization exposes none of the server's ` +
+      `tools. If the change is expected, review it and set each pin to the digest the server now serves; ` +
       `otherwise the instance comes back once the server serves the pinned definitions again.`,
   );
 }
 
+/**
+ * The fault for pinned tools the server does not list when the instance's
+ * credential reached it: {@link ConnectorCredentialRejectedError} (403), the
+ * same path and reasoning as an `include` entry the server does not list for
+ * that credential — a server may list only the tools a credential may use, so
+ * the message names both causes.
+ */
+function pinnedToolsHiddenError(
+  connectorName: string,
+  missing: readonly string[],
+  listedTools: readonly string[],
+): ConnectorCredentialRejectedError {
+  const named = missing.slice(0, DRIFT_NAMED_MAX).map((name) => `'${name}'`).join(', ');
+  const moreMissing = missing.length > DRIFT_NAMED_MAX ? `, … ${missing.length - DRIFT_NAMED_MAX} more` : '';
+  const offered = [...new Set(listedTools)];
+  const sample = offered.slice(0, 20);
+  const more = offered.length > sample.length ? `, … ${offered.length - sample.length} more` : '';
+  return new ConnectorCredentialRejectedError(
+    `connector-mcp provider: connector '${connectorName}' providerConfig.toolsSnapshot pins ${named}${moreMissing}, ` +
+      `which the MCP server does not list for the credential this instance sent. A server may list only the tools ` +
+      `a credential is allowed to use, and its tools/list answer cannot tell the two causes apart: either the ` +
+      `credential lacks the scopes or permissions these tools need — fix the credential, then set it again — or ` +
+      `the server no longer serves these tools — review the change and update providerConfig.toolsSnapshot. ` +
+      `For this credential, the server lists ${offered.length} tool(s): ` +
+      `${sample.map((name) => `'${name}'`).join(', ')}${more}.`,
+    403,
+  );
+}
+
 /** Whether {@link applyAuthToHeaders} puts the instance's credential on the http transport. */
 function sendsInstanceAuth(auth: ResolvedConnectorAuth | undefined): boolean {
   if (!auth || auth.type === 'none') return false;
 
@@ -45,15 +45,23 @@ function server(tools: McpToolDescriptor[]) {
     return { clientFactory, state };
 }
 
-function ctx(providerConfig: Record<string, unknown>): ConnectorProviderContext {
-    return { name: 'vendor', label: 'Vendor', type: 'api', providerConfig };
+function ctx(providerConfig: Record<string, unknown>, auth?: ConnectorProviderContext['auth']): ConnectorProviderContext {
+    return { name: 'vendor', label: 'Vendor', type: 'api', providerConfig, ...(auth ? { auth } : {}) };
 }
 
-/** Materialize against `tools`; resolves to the materialization or the thrown value. */
-async function materialize(tools: McpToolDescriptor[], providerConfig: Record<string, unknown>) {
+/**
+ * Materialize against `tools`; resolves to the materialization or the thrown
+ * value. `auth` is the instance's resolved credential: over http a bearer one
+ * reaches the server, which may then list only the tools it may use.
+ */
+async function materialize(
+    tools: McpToolDescriptor[],
+    providerConfig: Record<string, unknown>,
+    auth?: ConnectorProviderContext['auth'],
+) {
     const { clientFactory, state } = server(tools);
     const factory = createMcpProviderFactory({ clientFactory });
-    const outcome = await Promise.resolve(factory(ctx({ transport: http, ...providerConfig }))).then(
+    const outcome = await Promise.resolve(factory(ctx({ transport: http, ...providerConfig }, auth))).then(
         (mat: ConnectorMaterialization) => ({ mat, err: undefined as unknown }),
         (err: unknown) => ({ mat: undefined, err }),
     );
@@ -209,6 +217,69 @@ describe('mcp provider: providerConfig.toolsSnapshot pins each tool', () => {
     });
 });
 
+// A credentialed instance (a bearer `auth` over http reaches the server): a
+// server may list only the tools that credential may use, so a pinned tool it
+// does not list may be hidden from the credential rather than dropped — it
+// takes the credential path, both causes named, like an `include` entry. A
+// served tool that hashes differently is still the server's change.
+describe('mcp provider: toolsSnapshot on an instance whose credential reaches the server', () => {
+    const PIN = computeMcpToolsSnapshot([CREATE_ISSUE, LIST_ISSUES]);
+    const bearer = { type: 'bearer', token: 'narrow-token-value' } as unknown as ConnectorProviderContext['auth'];
+
+    function expectCredentialPath(err: unknown) {
+        expect(isConnectorCredentialRejected(err)).toBe(true);
+        expect((err as { status?: number }).status).toBe(403);
+        expect(isConnectorUpstreamChanged(err)).toBe(false);
+        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
+    }
+
+    it('an included and pinned tool the server does not list takes the credential path, naming both causes', async () => {
+        const { err, state } = await materialize(
+            [LIST_ISSUES, DELETE_REPO],
+            { include: ['create_issue', 'list_issues'], toolsSnapshot: PIN },
+            bearer,
+        );
+        expectCredentialPath(err);
+        const message = (err as Error).message;
+        expect(message).toContain("providerConfig.include names 'create_issue', which the MCP server does not list for the credential this instance sent");
+        expect(message).toContain('the credential lacks the scopes or permissions these tools need');
+        expect(message).not.toContain('narrow-token-value');
+        expect(state.closed).toBe(true);
+    });
+
+    it('a pinned tool the server does not list, with no include, takes the credential path too', async () => {
+        const { err, state } = await materialize([LIST_ISSUES, DELETE_REPO], { toolsSnapshot: PIN }, bearer);
+        expectCredentialPath(err);
+        const message = (err as Error).message;
+        expect(message).toMatch(
+            /^connector-mcp provider: connector 'vendor' providerConfig\.toolsSnapshot pins 'create_issue', which the MCP server does not list for the credential this instance sent\./,
+        );
+        expect(message).toContain('the credential lacks the scopes or permissions these tools need — fix the credential');
+        expect(message).toContain('the server no longer serves these tools — review the change and update providerConfig.toolsSnapshot');
+        expect(message).toContain("For this credential, the server lists 2 tool(s): 'list_issues', 'delete_repo'.");
+        expect(message).not.toContain('narrow-token-value');
+        expect(state.closed).toBe(true);
+    });
+
+    it('a served pinned tool that hashes differently is still CONNECTOR_UPSTREAM_CHANGED', async () => {
+        const rewritten = { ...CREATE_ISSUE, description: 'changed' };
+        const { err } = await materialize(
+            [rewritten, LIST_ISSUES],
+            { include: ['create_issue', 'list_issues'], toolsSnapshot: PIN },
+            bearer,
+        );
+        expectUpstreamChanged(err);
+        expect((err as Error).message).toContain("tool 'create_issue' changed");
+    });
+
+    it('matching pins materialize, and the credential counts as verified', async () => {
+        const { mat, err } = await materialize(SERVED, { include: ['create_issue', 'list_issues'], toolsSnapshot: PIN }, bearer);
+        expect(err).toBeUndefined();
+        expect(Object.keys(mat?.handlers ?? {})).toEqual(['create_issue', 'list_issues']);
+        expect(mat?.credentialVerified).toBe(true);
+    });
+});
+
 describe('mcp provider: a malformed toolsSnapshot is refused before connecting', () => {
     const digest = mcpToolDigest(CREATE_ISSUE);
 
 
@@ -1,30 +1,41 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * Upstream-availability classification for connector provider factories
- * (ADR-0097 follow-up, #3017).
+ * Failure classification for connector provider factories (ADR-0097
+ * follow-ups: #3017, #27237, #27401).
  *
- * A {@link ConnectorProviderFactory} can fail for two very different reasons:
+ * A {@link ConnectorProviderFactory} can fail in four ways, and the
+ * materializer treats each differently:
  *
- * 1. **Configuration faults** — invalid `providerConfig`, an unresolvable
- *    `credentialRef`, a name conflict. These are authoring mistakes; the
- *    materializer keeps them **fatal at boot** (ADR-0097 "fail loudly").
- * 2. **Operational faults** — the upstream the factory must contact to
- *    materialize (an MCP server's `tools/list`, a remote spec endpoint) is
- *    *temporarily unreachable*. Aborting the whole app boot for a transient
- *    network blip turns one degraded integration into a total outage.
+ * 1. **Configuration faults** — invalid `providerConfig`, a name conflict, a
+ *    shape the provider refuses. These are authoring mistakes, thrown with no
+ *    marker; the materializer keeps them **fatal at boot** (ADR-0097 "fail
+ *    loudly"), a skipped entry on reload.
+ * 2. **The upstream is unreachable** — the upstream the factory must contact
+ *    to materialize (an MCP server's `tools/list`, a remote spec endpoint) is
+ *    *temporarily unreachable*: {@link CONNECTOR_UPSTREAM_UNAVAILABLE}, most
+ *    conveniently a {@link ConnectorUpstreamUnavailableError}.
+ * 3. **The upstream refused the credential** — it answered, and refused the
+ *    credential the instance sent (HTTP 401 / 403, or a tool list narrowed to
+ *    what that credential may use): {@link CONNECTOR_CREDENTIAL_REJECTED},
+ *    a {@link ConnectorCredentialRejectedError}.
+ * 4. **The upstream changed** — it answered, and serves a definition that
+ *    differs from a pin the instance declares:
+ *    {@link CONNECTOR_UPSTREAM_CHANGED}, a {@link ConnectorUpstreamChangedError}.
  *
- * A factory signals case 2 by throwing an error whose `code` is
- * {@link CONNECTOR_UPSTREAM_UNAVAILABLE} — most conveniently a
- * {@link ConnectorUpstreamUnavailableError}. The materializer then **degrades**
- * that one instance instead of failing boot: it is registered in a `degraded`
- * state (visible via `GET /connectors`, dispatch fails with a clear error) and
- * re-materialization is retried with backoff and on every reconcile. Errors
- * without the marker keep the fail-loud contract unchanged.
+ * Each of the three markers makes the materializer **degrade** that one
+ * instance instead of failing boot: it is registered in a `degraded` state
+ * (visible via `GET /connectors`, dispatch fails with the factory's message)
+ * with log records worded for its cause. An unreachable or changed upstream is
+ * re-materialized with backoff and on every reconcile; a refused credential is
+ * retried on that backoff only when its value can change where the process
+ * cannot see it (the marker's own TSDoc says when). Errors without a marker
+ * keep the fail-loud contract unchanged.
  *
- * The check is **structural** ({@link isConnectorUpstreamUnavailable} reads
- * `code`, never `instanceof`), so classification survives package-manager
- * module duplication across the plugin/host boundary.
+ * The checks are **structural** ({@link isConnectorUpstreamUnavailable},
+ * {@link isConnectorCredentialRejected} and {@link isConnectorUpstreamChanged}
+ * read `code`, never `instanceof`), so classification survives
+ * package-manager module duplication across the plugin/host boundary.
  */
 
 /** Marker `code` for an operational (retryable) provider-factory failure. */