From 25af2c9fed8182494779dc9ca5c78c953ba5c1b4 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 31 Oct 2026 05:14:12 +0000
Subject: [PATCH 1/7] fix(connector-mcp): an include a credentialed server does
 not list takes the credential path

When providerConfig.include names a tool the MCP server's tools/list does
not carry and the handshake carried the instance's credential, the refusal
is raised as ConnectorCredentialRejectedError (status 403), naming both
causes the answer cannot tell apart: the credential's scopes hide the tool,
or the declaration names a tool the server does not have. An instance whose
handshake carried no credential keeps the plain configuration fault.

Claude-Session: https://claude.ai/code/session_017xRBcVBKAFk1ntXSjvPt7U
Co-authored-by: Claude <noreply@anthropic.com>
---
 .../connector-mcp/src/mcp-provider.ts         | 70 ++++++++++++++-----
 1 file changed, 54 insertions(+), 16 deletions(-)

diff --git a/packages/connectors/connector-mcp/src/mcp-provider.ts b/packages/connectors/connector-mcp/src/mcp-provider.ts
index ae66f3def90..adfc23e431f 100644
--- a/packages/connectors/connector-mcp/src/mcp-provider.ts
+++ b/packages/connectors/connector-mcp/src/mcp-provider.ts
@@ -213,8 +213,15 @@ async function credentialRejectionStatus(err: unknown): Promise<number | undefin
  * tool names, with the `openapi` provider's meaning. An `include` that is not
  * an array of non-empty strings is refused before connecting, and an entry
  * naming a tool the server's `tools/list` does not carry is refused after
- * listing (the connection is closed first); both are configuration faults,
- * thrown plain. The instance never falls back to exposing every tool.
+ * listing (the connection is closed first); both are configuration faults.
+ * The instance never falls back to exposing every tool. The second refusal is
+ * thrown plain when the handshake carried no instance credential, and as
+ * {@link ConnectorCredentialRejectedError} when it did: a server may list only
+ * the tools a credential is allowed to use (GitHub's hides a tool a classic
+ * token's scopes do not cover), and nothing in a `tools/list` answer tells a
+ * tool hidden from this credential apart from one the server never had, so the
+ * refusal names both and takes the credential's path — the instance degraded,
+ * a stored credential marked `rejected`, the boot not failed.
  */
 export function createMcpProviderFactory(deps: McpProviderDeps = {}): ConnectorProviderFactory {
   return async (ctx) => {
@@ -300,33 +307,64 @@ export function createMcpProviderFactory(deps: McpProviderDeps = {}): ConnectorP
         { cause: err },
       );
     }
+    // [#27237] The handshake carried the instance's credential only over
+    // http, and only as a header (an api-key `paramName` is not sent): then
+    // the server's answer was given to that credential.
+    const credentialSent = transport.kind === 'http' && sendsInstanceAuth(ctx.auth);
     if (includeList) {
-      // An entry naming a tool the server does not list is a configuration
-      // fault, thrown plain — fatal at boot, a skipped entry on reload — after
-      // the connection is released. Ignoring it would bring the instance up
-      // without the tool the author listed (a typo, or a tool the server
-      // renamed or dropped), and the first sign would be a flow failing at
-      // run time.
+      // An entry naming a tool the server does not list is refused after the
+      // connection is released. Ignoring it would bring the instance up
+      // 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.
       const offered = new Set(listedTools);
       const unknown = [...new Set(includeList)].filter((entry) => !offered.has(entry));
       if (unknown.length > 0) {
         await bundle.close().catch(() => {});
+        const named = unknown.map((entry) => `'${entry}'`).join(', ');
         // At most 20 of the server's tool names, as the openapi refusal lists.
         const sample = [...offered].slice(0, 20);
         const more = offered.size > sample.length ? `, … ${offered.size - sample.length} more` : '';
+        const listed =
+          `the server lists ${offered.size} tool(s): ` + `${sample.map((name) => `'${name}'`).join(', ')}${more}.`;
+        if (credentialSent) {
+          // A server may list only the tools the credential it was sent is
+          // allowed to use: GitHub's hides each tool a classic token's scopes
+          // do not cover, and its answer carries nothing about what it hid —
+          // no field in the tools/list result, no response header. So a
+          // missing tool is the credential's fault or the declaration's, and
+          // which one cannot be read off the answer. It takes the credential's
+          // path, like a 401 / 403 above: the instance degraded naming both
+          // causes, a stored credential marked `rejected` (cleared by setting
+          // it again, or by a handshake that lists every entry), and never a
+          // failed boot for a value the administrator supplies and can fix.
+          // Status 403: the server answered 200 and refused nothing in so many
+          // words, and 403 is the status a credential short of the scopes a
+          // resource needs is answered with (RFC 6750 §3.1, insufficient_scope;
+          // GitHub's server answers a tools/call outside its token's scopes
+          // that way). The message quotes no HTTP status for that reason.
+          throw new ConnectorCredentialRejectedError(
+            `connector-mcp provider: connector '${ctx.name}' providerConfig.include names ${named}, 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 declaration names a tool this server does not have — fix providerConfig.include. ` +
+              `For this credential, ${listed}`,
+            403,
+          );
+        }
+        // No instance credential reached the server, so its list is not one
+        // filtered for a credential: a configuration fault, thrown plain —
+        // fatal at boot, a skipped entry on reload.
         throw new Error(
           `connector-mcp provider: connector '${ctx.name}' providerConfig.include names ` +
-            `${unknown.map((entry) => `'${entry}'`).join(', ')}, which the MCP server does not list. ` +
-            `Each entry must be the name of a tool from the server's tools/list; ` +
-            `the server lists ${offered.size} tool(s): ` +
-            `${sample.map((name) => `'${name}'`).join(', ')}${more}.`,
+            `${named}, which the MCP server does not list. ` +
+            `Each entry must be the name of a tool from the server's tools/list; ${listed}`,
         );
       }
     }
-    // [#27237] The handshake carried the instance's credential only over
-    // http, and only as a header (an api-key `paramName` is not sent): then
-    // the server's answer proved it.
-    const credentialVerified = transport.kind === 'http' && sendsInstanceAuth(ctx.auth);
+    // [#27237] Then the server's answer proved the credential.
+    const credentialVerified = credentialSent;
     return {
       def: bundle.def,
       handlers: bundle.handlers,

From f4b220aa9a2cdb30142f9d25e7f7098bd3df7489 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 31 Oct 2026 05:20:04 +0000
Subject: [PATCH 2/7] test(connector-mcp): pin the credential path for an
 include a credentialed server hides, with docs and changeset

The three probes as permanent tests, on the real provider and materializer
and the real credential store (ObjectQL over SQLite): an environment
credential degrades the instance instead of failing the boot and recovers
once the scopes cover the tools; a stored credential is marked rejected and
held, and a better-scoped value recovers it without a restart; with no
credential the boot still fails as a declaration fault.

Claude-Session: https://claude.ai/code/session_017xRBcVBKAFk1ntXSjvPt7U
Co-authored-by: Claude <noreply@anthropic.com>
---
 .../28311-mcp-include-scope-hidden-tools.md   |  14 +
 content/docs/automation/connectors.mdx        |  21 +-
 .../connectors/connector-mcp/package.json     |   3 +
 .../src/mcp-include-credential-scope.test.ts  | 353 ++++++++++++++++++
 pnpm-lock.yaml                                |   9 +
 5 files changed, 394 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/28311-mcp-include-scope-hidden-tools.md
 create mode 100644 packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts

diff --git a/.changeset/28311-mcp-include-scope-hidden-tools.md b/.changeset/28311-mcp-include-scope-hidden-tools.md
new file mode 100644
index 00000000000..393f0129ee8
--- /dev/null
+++ b/.changeset/28311-mcp-include-scope-hidden-tools.md
@@ -0,0 +1,14 @@
+---
+'@objectstack/connector-mcp': patch
+---
+
+fix(connector-mcp): when a server that was sent the instance's credential does not list an `include`d tool, the instance is degraded as a credential refusal instead of failing the boot as a declaration fault
+
+Clause-②: no
+Metadata-protocol: none
+
+Some MCP servers list only the tools the credential they are sent may use: GitHub's hides each tool a classic personal access token's scopes do not cover. Its `tools/list` answer says nothing about what it hid, so a tool missing from it may be hidden from this credential or may not exist on the server at all.
+
+- **Before.** When `providerConfig.include` named a tool the server did not list, the `mcp` provider refused with a plain configuration fault in every case. With the credential in an environment variable, the whole boot failed. With a credential stored through the credential door, the instance was degraded with a reason telling the administrator to fix the app's declaration.
+- **Now.** When the handshake carried the instance's `auth` credential (an `http` transport, the credential sent as a header), the refusal is a `ConnectorCredentialRejectedError` with status `403`. Its message names the missing tools and the tools the server does list for that credential, and it names both causes with the fix for each: give the credential the scopes those tools need and set it again, or fix `providerConfig.include`. The materializer handles it as it handles a `401` / `403`: the instance is degraded and the boot does not fail. A stored credential is marked `rejected` and held until it is set again; an environment or vault credential is retried on the backoff, so widening the token's scopes where it was issued recovers the instance without a restart.
+- **Unchanged.** An instance whose handshake carried no credential (no `auth`, an `api-key` sent as a query parameter, or a `stdio` transport) keeps the plain configuration fault, fatal at boot, with the same message as before.
diff --git a/content/docs/automation/connectors.mdx b/content/docs/automation/connectors.mdx
index 794faad7dd7..4fb92d614b2 100644
--- a/content/docs/automation/connectors.mdx
+++ b/content/docs/automation/connectors.mdx
@@ -237,9 +237,16 @@ keep a destructive tool away from your flows and agents. It must be an array of
 tool names; any other shape (a string such as `include: 'web_search'`, an
 object) fails the boot before connecting, and never falls back to exposing
 every tool. An entry the server's `tools/list` does not carry — a typo, or a
-tool the server renamed or dropped — fails the boot with an error naming the
-entry and listing the server's tools; it is never ignored. Leave `include` out
-to expose every tool.
+tool the server renamed or dropped — is never ignored: the refusal names the
+entry and lists the server's tools. On an instance that sends no credential it
+fails the boot. When the instance sends its `auth` credential, the entry may
+instead be a tool the server hides from that credential: some servers list
+only the tools a credential is allowed to use (GitHub's hides each tool a
+classic token's scopes do not cover), and the answer does not say what it hid.
+That instance is degraded as a credential the upstream refuses (below), never
+failing the boot, and its reason names both causes: a credential without the
+scopes those tools need, or a declaration naming a tool the server does not
+have. Leave `include` out to expose every tool.
 
 <Callout type="warn">
 **Declarative stdio transports are denied by default.** Materializing one
@@ -365,7 +372,9 @@ plus a `credentialNote` naming the ones still to set.
 
 **A credential the upstream refuses** (HTTP `401` / `403`) degrades the
 instance, with a reason quoting the upstream's message, never the value. An
-`mcp` instance finds this out when it connects. A `rest` or `openapi` instance
+`mcp` instance finds this out when it connects, and treats a server that
+accepts the credential but does not list a tool its `include` names the same
+way. A `rest` or `openapi` instance
 finds out on the first call answering `401` / `403`; that call returns its
 answer as usual, and the instance is degraded after it. What happens next
 depends on where the value came from:
@@ -591,11 +600,11 @@ retry):
 | `auth` is a grant-bearing kind (`oauth2`, `app-credential`) on a server that does not yet run its per-dispatch resolution | **Not fatal**: the instance registers **degraded**, naming the kind, and the upstream is never called without its credential; a datasource borrowing it is refused with `422` |
 | `auth` is `signed` on a provider that does not say it applies the request signer | **Hard boot error** naming the instance, the scheme and the provider: its calls would go out unsigned — declare it through `rest` or `openapi` |
 | `credentialRef` resolves to nothing | **Not fatal**: the instance registers **degraded**, naming the reference — set it (`PUT …/credential-refs/:ref`), and it materializes without a restart |
-| The upstream refuses the credential (`401` / `403`) | **Not fatal**: the instance registers **degraded**. A stored credential is marked `rejected` and waits until it is set again (or a restart); an environment or vault credential is retried on the backoff |
+| The upstream refuses the credential (`401` / `403`), or an `mcp` server sent the credential does not list a tool the instance's `include` names | **Not fatal**: the instance registers **degraded**. A stored credential is marked `rejected` and waits until it is set again (or a restart); an environment or vault credential is retried on the backoff |
 | Instance `name` collides with a plugin-registered connector | **Hard boot error** — there is no silent precedence between the two worlds |
 | stdio transport without host opt-in | **Hard boot error** with the `declarativeStdio` fix inline — a security rejection is never retried |
 | MCP server unreachable / `tools/list` fails; remote spec URL unreachable or transiently failing (408/429/5xx) | **Not fatal**: the instance registers **degraded** (visible on `GET /api/v1/automation/connectors` with the reason), dispatches fail with that reason, and the platform retries on a 5s→5min backoff — recovery is automatic |
-| A retry of a degraded instance reaches the upstream and meets a configuration fault (an `include` naming a tool or operation the upstream does not offer) | **Not fatal**: the instance stays **degraded**, now with the configuration reason, and is **not retried** — dispatches fail saying to edit its declaration; an edit of the entry (or a restart) re-attempts it |
+| A retry of a degraded instance reaches the upstream and meets a configuration fault (an `include` naming a tool or operation the upstream does not offer; on an `mcp` instance that sends a credential, the credential row above applies instead) | **Not fatal**: the instance stays **degraded**, now with the configuration reason, and is **not retried** — dispatches fail saying to edit its declaration; an edit of the entry (or a restart) re-attempts it |
 | Wrong spec URL (other 4xx) or unparseable document | Configuration fault — **hard boot error** |
 | A `connector_action` input that, once evaluated, breaks the action's `inputSchema` (a missing `required` parameter, a wrong `type`) | **The step fails before dispatch** with `VALIDATION_ERROR`, naming each parameter path, and nothing is sent; a `fault` edge or `try_catch` can route it. Supply the parameter or send the declared type: text is never converted, so cast it in a CEL envelope (`int()`, `double()`, `bool()`). `GET /api/v1/automation/connectors` lists the schema; `os validate` does not judge the input against the `inputSchema` yet |
 | A bad entry arrives via **runtime reload** (a Studio publish, a direct active save through `PUT /api/v1/meta/connector/:name`, or a delete, made on any replica — peers reconcile on [cluster lane 2](/docs/kernel/cluster#62-the-cluster-invalidation-family); or a dev reload) | Logged and **skipped**, never crashing the live server; a changed instance's old connector keeps serving until its replacement materializes |
diff --git a/packages/connectors/connector-mcp/package.json b/packages/connectors/connector-mcp/package.json
index 80e8c2f9ee2..79b4215c2fc 100644
--- a/packages/connectors/connector-mcp/package.json
+++ b/packages/connectors/connector-mcp/package.json
@@ -32,6 +32,9 @@
     "@objectstack/spec": "workspace:*"
   },
   "devDependencies": {
+    "@objectstack/driver-sql": "workspace:*",
+    "@objectstack/objectql": "workspace:*",
+    "@objectstack/platform-objects": "workspace:*",
     "@objectstack/service-automation": "workspace:*",
     "@types/node": "^26.6.5",
     "typescript": "^6.0.3",
diff --git a/packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts b/packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts
new file mode 100644
index 00000000000..15ae41a80ad
--- /dev/null
+++ b/packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts
@@ -0,0 +1,353 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * A server that lists only the tools a credential may use, against an
+ * `include` that names one it hides.
+ *
+ * Some MCP servers filter `tools/list` by the credential they are sent:
+ * GitHub's hides each tool a classic token's scopes do not cover, and its
+ * answer says nothing about what it hid. So when `providerConfig.include`
+ * names a tool the listing does not carry, the instance cannot tell a
+ * credential short of scopes from a declaration naming a tool the server
+ * never had. When the handshake carried the instance's credential the
+ * refusal takes the credential's path, as a 401 / 403 does: the instance is
+ * degraded naming both causes, a stored credential is marked `rejected`, and
+ * the boot does not fail. Without a credential it stays the configuration
+ * fault it was, fatal at boot.
+ *
+ * The fake server below answers by the bearer token it was sent; the
+ * credential store is the real one, on ObjectQL over SQLite. Values are
+ * obvious dummies.
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { LiteKernel } from '@objectstack/core';
+import { ObjectQL } from '@objectstack/objectql';
+import { SqlDriver } from '@objectstack/driver-sql';
+import { SysSecret } from '@objectstack/platform-objects';
+import { AutomationServicePlugin, type AutomationEngine } from '@objectstack/service-automation';
+import type { CryptoContext, CryptoHandle, ICryptoProvider } from '@objectstack/spec/contracts';
+import type { ConnectorProviderContext } from '@objectstack/spec/integration';
+import { isConnectorCredentialRejected, isConnectorUpstreamUnavailable } from '@objectstack/spec/integration';
+import type { McpClientLike, McpToolDescriptor, McpTransport } from './mcp-connector.js';
+import { ConnectorMcpPlugin } from './connector-mcp-plugin.js';
+import { createMcpProviderFactory } from './mcp-provider.js';
+
+const REF = 'DUMMY_VENDOR_MCP_TOKEN';
+/** Its scopes cover only `whoami`. */
+const NARROW_TOKEN = 'dummy-narrow-token-aaaa-0001';
+/** Its scopes cover every tool. */
+const WIDE_TOKEN = 'dummy-wide-token-bbbb-0002';
+const URL = 'https://mcp.vendor.example/mcp';
+const INCLUDE = ['search_invoices', 'read_invoice'];
+const ADMIN = { userId: 'usr_admin_scope' } as never;
+const SYSTEM = { isSystem: true } as const;
+
+const TOOLS: McpToolDescriptor[] = [
+    { name: 'whoami', description: 'The token owner' },
+    { name: 'search_invoices', description: 'Search invoices', inputSchema: { type: 'object' } },
+    { name: 'read_invoice', description: 'Read one invoice', inputSchema: { type: 'object' } },
+    { name: 'void_invoice', description: 'Void an invoice', inputSchema: { type: 'object' } },
+];
+
+/**
+ * A fake MCP server that lists only the tools the bearer token it was sent may
+ * use — `scopes` maps a token to its tool names. A request with no token, or
+ * an unknown one, sees `anonymous` (every tool by default). Records each
+ * connection and close.
+ */
+function scopedServer(scopes: Record<string, string[]>, anonymous: string[] = TOOLS.map((t) => t.name)) {
+    const state = { connects: [] as McpTransport[], closed: 0 };
+    const tokenOf = (t: McpTransport) =>
+        t.kind === 'http' ? t.headers?.Authorization?.replace(/^Bearer /, '') : undefined;
+    const clientFactory = async (transport: McpTransport): Promise<McpClientLike> => {
+        state.connects.push(transport);
+        const token = tokenOf(transport);
+        const allowed = (token !== undefined ? scopes[token] : undefined) ?? anonymous;
+        return {
+            listTools: async () => TOOLS.filter((t) => allowed.includes(t.name)),
+            callTool: async (name) => ({ content: [{ type: 'text', text: `${name} answered` }] }),
+            close: async () => { state.closed += 1; },
+        };
+    };
+    return { clientFactory, state, scopes };
+}
+
+function ctx(partial: Partial<ConnectorProviderContext>): ConnectorProviderContext {
+    return {
+        name: 'vendor_mcp',
+        label: 'Vendor',
+        type: 'api',
+        providerConfig: { transport: { kind: 'http', url: URL }, include: INCLUDE },
+        ...partial,
+    };
+}
+
+async function thrownBy(run: () => unknown): Promise<unknown> {
+    return Promise.resolve()
+        .then(run)
+        .then(
+            () => { throw new Error('expected a refusal'); },
+            (e: unknown) => e,
+        );
+}
+
+describe('mcp provider: an include the server does not list for the credential it was sent', () => {
+    it('is a credential refusal (403) naming both causes, the missing tools and the listed ones, and closes the client', async () => {
+        const server = scopedServer({ [NARROW_TOKEN]: ['whoami'] });
+        const factory = createMcpProviderFactory({ clientFactory: server.clientFactory });
+        const err = await thrownBy(() => factory(ctx({ auth: { type: 'bearer', token: NARROW_TOKEN } })));
+
+        expect(err).toBeInstanceOf(Error);
+        expect(isConnectorCredentialRejected(err)).toBe(true);
+        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
+        expect((err as { status?: unknown }).status).toBe(403);
+        const message = (err as Error).message;
+        expect(message).toMatch(
+            /^connector-mcp provider: connector 'vendor_mcp' providerConfig\.include names 'search_invoices', 'read_invoice', which the MCP server does not list for the credential this instance sent\./,
+        );
+        // Both causes, and what to fix for each.
+        expect(message).toContain('the credential lacks the scopes or permissions these tools need — fix the credential');
+        expect(message).toContain('the declaration names a tool this server does not have — fix providerConfig.include');
+        expect(message).toContain("For this credential, the server lists 1 tool(s): 'whoami'.");
+        expect(message.includes(NARROW_TOKEN)).toBe(false);
+        expect(server.state.connects).toHaveLength(1);
+        expect(server.state.closed).toBe(1);
+    });
+
+    it.each([
+        ['an http instance with no auth', {}],
+        ['an http instance whose api-key rides a query parameter (never sent on the transport)', {
+            auth: { type: 'api-key', key: NARROW_TOKEN, headerName: 'X-API-Key', paramName: 'key' } as const,
+        }],
+    ])('control: %s keeps the plain configuration fault', async (_shape, partial) => {
+        const server = scopedServer({});
+        const factory = createMcpProviderFactory({ clientFactory: server.clientFactory });
+        const err = await thrownBy(() =>
+            factory(ctx({ ...partial, providerConfig: { transport: { kind: 'http', url: URL }, include: ['nope'] } })),
+        );
+        expect(err).toBeInstanceOf(Error);
+        expect(isConnectorCredentialRejected(err)).toBe(false);
+        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
+        expect((err as Error).message).toMatch(
+            /^connector-mcp provider: connector 'vendor_mcp' providerConfig\.include names 'nope', which the MCP server does not list\. Each entry must be the name of a tool from the server's tools\/list; the server lists 4 tool\(s\)/,
+        );
+        expect(server.state.closed).toBe(1);
+    });
+
+    it('control: a stdio instance with resolved auth keeps the plain fault — auth is not sent to a stdio server', async () => {
+        const server = scopedServer({});
+        const factory = createMcpProviderFactory({ clientFactory: server.clientFactory, declarativeStdio: true });
+        const err = await thrownBy(() =>
+            factory(ctx({
+                auth: { type: 'bearer', token: NARROW_TOKEN },
+                providerConfig: { transport: { kind: 'stdio', command: 'vendor-mcp' }, include: ['nope'] },
+            })),
+        );
+        expect(isConnectorCredentialRejected(err)).toBe(false);
+        expect((err as Error).message).toContain("providerConfig.include names 'nope', which the MCP server does not list.");
+    });
+
+    it('control: a credential whose listing carries every entry materializes exactly those tools, proven', async () => {
+        const server = scopedServer({ [WIDE_TOKEN]: TOOLS.map((t) => t.name) });
+        const mat = await createMcpProviderFactory({ clientFactory: server.clientFactory })(
+            ctx({ auth: { type: 'bearer', token: WIDE_TOKEN } }),
+        );
+        expect(Object.keys(mat.handlers).sort()).toEqual(['read_invoice', 'search_invoices']);
+        expect(mat.credentialVerified).toBe(true);
+        expect(server.state.closed).toBe(0);
+    });
+});
+
+// ── Through the materializer: the boot, the credential door, the listing ────
+
+/** Reversible stand-in cipher — the store's seam is the engine's, not the cipher's. */
+function fakeCrypto(): ICryptoProvider {
+    let n = 0;
+    return {
+        async encrypt(plain: string, _ctx: CryptoContext): Promise<CryptoHandle> {
+            n += 1;
+            return { id: `sec_${n}`, kmsKeyId: 'test', alg: 'test-rev', version: 1, ciphertext: [...plain].reverse().join('') };
+        },
+        async decrypt(handle: CryptoHandle): Promise<string> {
+            return [...handle.ciphertext].reverse().join('');
+        },
+        async rotateKey(handle: CryptoHandle): Promise<CryptoHandle> {
+            return { ...handle, version: handle.version + 1 };
+        },
+        digest: (plain: string) => `d:${plain.length}`,
+        keyedDigest: async (plain: string) => `k:${plain.length}`,
+    };
+}
+
+const flush = () => new Promise<void>((r) => setTimeout(r, 0));
+const kernels: LiteKernel[] = [];
+const engines: ObjectQL[] = [];
+const envKeys: string[] = [];
+afterEach(async () => {
+    for (const k of kernels.splice(0)) await k.shutdown().catch(() => {});
+    for (const e of engines.splice(0)) {
+        try { await (e as unknown as { destroy?: () => Promise<void> }).destroy?.(); } catch { /* noop */ }
+    }
+    for (const key of envKeys.splice(0)) delete process.env[key];
+    vi.restoreAllMocks();
+});
+
+/** Everything the process prints while a test runs: the kernel logger (JSON) and any console call. */
+function captureOutput(): { text: () => string } {
+    const chunks: string[] = [];
+    const keep = ((c: string | Uint8Array) => { chunks.push(String(c)); return true; }) as never;
+    vi.spyOn(process.stdout, 'write').mockImplementation(keep);
+    vi.spyOn(process.stderr, 'write').mockImplementation(keep);
+    for (const m of ['log', 'info', 'warn', 'error', 'debug'] as const) {
+        vi.spyOn(console, m).mockImplementation((...args: unknown[]) => { chunks.push(args.map(String).join(' ')); });
+    }
+    return { text: () => chunks.join('\n') };
+}
+
+function declared(withAuth = true) {
+    return {
+        name: 'vendor_mcp',
+        label: 'Vendor MCP',
+        type: 'api',
+        provider: 'mcp',
+        providerConfig: { transport: { kind: 'http', url: URL }, include: INCLUDE },
+        ...(withAuth ? { auth: { type: 'bearer', credentialRef: REF } } : {}),
+        _packageId: 'com.example.vendor',
+    };
+}
+
+/**
+ * The automation service, the real `mcp` provider over `server`, and the real
+ * credential store on ObjectQL over in-memory SQLite. The harness stands in
+ * for the ObjectQL plugin (hence its name, which the automation plugin orders
+ * itself after): it serves the declared entries, the data engine, and a
+ * `manifest` service that registers the objects the automation plugin
+ * contributes — the credential store's among them.
+ */
+async function boot(entries: unknown[], server: ReturnType<typeof scopedServer>) {
+    const ql = new ObjectQL();
+    engines.push(ql);
+    const driver = new SqlDriver({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true });
+    await driver.connect();
+    ql.registerDriver(driver, true);
+    await ql.init();
+    const registry = (ql as unknown as { registry: { registerObject(o: unknown, pkg: string): void } }).registry;
+    registry.registerObject(SysSecret, 'test');
+    ql.setCryptoProvider(fakeCrypto());
+
+    const kernel = new LiteKernel({ logger: { level: 'debug', format: 'json' } } as never);
+    kernels.push(kernel);
+    let captured: { trigger(event: string): Promise<void> } | undefined;
+    kernel.use({
+        name: 'com.objectstack.engine.objectql',
+        type: 'standard',
+        version: '1.0.0',
+        async init(c: { registerService(name: string, service: unknown): void }) {
+            captured = c as never;
+            c.registerService('objectql', { registry: { listItems: (t: string) => (t === 'connector' ? entries : []) } });
+            c.registerService('data', ql);
+            c.registerService('manifest', {
+                register(m: { objects?: unknown[] }) {
+                    for (const o of m.objects ?? []) registry.registerObject(o, 'test');
+                },
+            });
+        },
+        // Every plugin has inited — the automation plugin's objects are registered.
+        async start() { await ql.syncSchemas(); },
+    } as never);
+    kernel.use(new AutomationServicePlugin({ suspendedRunStore: 'memory', credentialResolver: () => undefined }));
+    kernel.use(new ConnectorMcpPlugin({ clientFactory: server.clientFactory }));
+    await kernel.bootstrap();
+    await flush();
+    const engine = kernel.getService('automation') as AutomationEngine;
+    const descriptor = () => engine.getConnectorDescriptors().find((d) => d.name === 'vendor_mcp');
+    /** A soft reconcile with nothing changed — the `metadata:reloaded` path. */
+    const reload = async () => {
+        await captured!.trigger('metadata:reloaded');
+        await flush();
+    };
+    return { engine, ql, kernel, descriptor, reload };
+}
+
+describe('the materializer: a credential whose scopes hide an included tool degrades the instance, never the boot', () => {
+    it('environment credential: the boot does not fail; degraded, listed `rejected`; recovers once the scopes cover the tools', async () => {
+        process.env[REF] = NARROW_TOKEN;
+        envKeys.push(REF);
+        const out = captureOutput();
+        const server = scopedServer({ [NARROW_TOKEN]: ['whoami'] });
+        const { engine, descriptor, reload } = await boot([declared()], server);
+
+        expect(descriptor()).toMatchObject({ state: 'degraded', actions: [] });
+        const reason = engine.getConnectorDegradedReason('vendor_mcp');
+        expect(reason).toContain(
+            "providerConfig.include names 'search_invoices', 'read_invoice', which the MCP server does not list for the credential this instance sent.",
+        );
+        // A value the door does not hold is retried on the backoff, not held.
+        expect(engine.getConnectorDegradedHold('vendor_mcp')).toBeUndefined();
+        const [listed] = await engine.listConnectorCredentialRefs();
+        expect(listed).toMatchObject({ ref: REF, status: 'rejected', source: 'env' });
+        expect(engine.resolveConnectorAction('vendor_mcp', 'search_invoices')).toBeUndefined();
+
+        // The administrator widens the token's scopes where it was issued;
+        // the value is unchanged. The next attempt (a reconcile here, the
+        // backoff timer in a running server) lists the tools.
+        server.scopes[NARROW_TOKEN] = TOOLS.map((t) => t.name);
+        await reload();
+        expect(descriptor()).toMatchObject({ state: 'ready' });
+        expect(descriptor()!.actions.map((a) => a.key).sort()).toEqual(['read_invoice', 'search_invoices']);
+        expect((await engine.listConnectorCredentialRefs())[0]).toMatchObject({ status: 'set', source: 'env' });
+
+        expect(out.text().includes(NARROW_TOKEN)).toBe(false);
+        expect(out.text()).not.toContain('Fix its declaration');
+    });
+
+    it('stored credential: degraded with the credential reason and the row `rejected`; held; a better-scoped value recovers it, no restart', async () => {
+        const out = captureOutput();
+        const server = scopedServer({ [NARROW_TOKEN]: ['whoami'], [WIDE_TOKEN]: TOOLS.map((t) => t.name) });
+        const { engine, ql, descriptor, reload } = await boot([declared()], server);
+        // Nothing set yet: degraded naming the reference, nothing dialled.
+        expect(engine.getConnectorDegradedReason('vendor_mcp')).toContain(`credential '${REF}'`);
+        expect(server.state.connects).toHaveLength(0);
+
+        const entry = await engine.setConnectorCredential({ ref: REF, value: NARROW_TOKEN, context: ADMIN });
+        const reason = engine.getConnectorDegradedReason('vendor_mcp');
+        expect(reason).toContain(
+            "providerConfig.include names 'search_invoices', 'read_invoice', which the MCP server does not list for the credential this instance sent.",
+        );
+        expect(reason).toContain('fix the credential, then set it again');
+        expect(entry).toMatchObject({ ref: REF, status: 'rejected', source: 'object', statusReason: reason });
+        expect(entry.connectors[0]).toMatchObject({ name: 'vendor_mcp', state: 'degraded', degradedReason: reason });
+        // Held on the stored value: setting it again is what re-attempts it.
+        expect(engine.getConnectorDegradedHold('vendor_mcp')).toEqual({ kind: 'credential', ref: REF });
+        const dialled = server.state.connects.length;
+        await reload();
+        expect(server.state.connects).toHaveLength(dialled);
+        // The row itself, as the engine reads it.
+        const rows = (await ql.find('sys_connector_credential', { context: SYSTEM } as never)) as Array<Record<string, unknown>>;
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toMatchObject({ ref: REF, status: 'rejected', status_reason: reason });
+
+        // A value whose scopes cover the tools: ready, those tools only, the row back to `set`.
+        const recovered = await engine.setConnectorCredential({ ref: REF, value: WIDE_TOKEN, context: ADMIN });
+        expect(descriptor()).toMatchObject({ state: 'ready' });
+        expect(descriptor()!.actions.map((a) => a.key).sort()).toEqual(['read_invoice', 'search_invoices']);
+        expect(recovered).toMatchObject({ status: 'set', source: 'object' });
+        expect(recovered.lastVerifiedAt).toEqual(expect.any(String));
+
+        const text = out.text();
+        expect(text.includes(NARROW_TOKEN) || text.includes(WIDE_TOKEN)).toBe(false);
+        expect(text).not.toContain('Fix its declaration');
+    });
+
+    it('control: an instance with no credential and an include the server does not list still fails the boot', async () => {
+        captureOutput();
+        const server = scopedServer({}, ['whoami']);
+        const kernelBoot = await Promise.resolve(boot([declared(false)], server)).then(() => undefined, (e: unknown) => e);
+        expect(kernelBoot).toBeInstanceOf(Error);
+        const message = (kernelBoot as Error).message;
+        expect(message).toContain("failed to materialize connector instance 'vendor_mcp' via provider 'mcp'");
+        expect(message).toContain("providerConfig.include names 'search_invoices', 'read_invoice', which the MCP server does not list.");
+        expect(message).not.toContain('for the credential this instance sent');
+    });
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index aece0002023..022a7b86239 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -844,6 +844,15 @@ importers:
         specifier: workspace:*
         version: link:../../spec
     devDependencies:
+      '@objectstack/driver-sql':
+        specifier: workspace:*
+        version: link:../../drivers/driver-sql
+      '@objectstack/objectql':
+        specifier: workspace:*
+        version: link:../../objectql
+      '@objectstack/platform-objects':
+        specifier: workspace:*
+        version: link:../../platform-objects
       '@objectstack/service-automation':
         specifier: workspace:*
         version: link:../../services/service-automation

From 9990f97cc750d58d48c1e6c79704780568f4eed6 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 31 Oct 2026 05:23:42 +0000
Subject: [PATCH 3/7] docs(spec, service-automation): the credential-rejected
 marker and the rejected row also cover an mcp listing that withholds an
 included tool

ConnectorCredentialRejectedError's TSDoc and its status member, and the
sys_connector_credential status description, named only a 401 / 403. The
mcp provider now also raises the marker (status 403) for a server that
accepted the credential and did not list a tool the instance's include
names, so each text names that case too. Comments only in spec.

Claude-Session: https://claude.ai/code/session_017xRBcVBKAFk1ntXSjvPt7U
Co-authored-by: Claude <noreply@anthropic.com>
---
 .../28311-mcp-include-scope-hidden-tools.md   |  2 ++
 .../src/sys-connector-credential.object.ts    |  2 +-
 .../integration/connector-provider-errors.ts  | 20 +++++++++++++++----
 3 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/.changeset/28311-mcp-include-scope-hidden-tools.md b/.changeset/28311-mcp-include-scope-hidden-tools.md
index 393f0129ee8..a6c8773fdbc 100644
--- a/.changeset/28311-mcp-include-scope-hidden-tools.md
+++ b/.changeset/28311-mcp-include-scope-hidden-tools.md
@@ -1,5 +1,6 @@
 ---
 '@objectstack/connector-mcp': patch
+'@objectstack/service-automation': patch
 ---
 
 fix(connector-mcp): when a server that was sent the instance's credential does not list an `include`d tool, the instance is degraded as a credential refusal instead of failing the boot as a declaration fault
@@ -12,3 +13,4 @@ Some MCP servers list only the tools the credential they are sent may use: GitHu
 - **Before.** When `providerConfig.include` named a tool the server did not list, the `mcp` provider refused with a plain configuration fault in every case. With the credential in an environment variable, the whole boot failed. With a credential stored through the credential door, the instance was degraded with a reason telling the administrator to fix the app's declaration.
 - **Now.** When the handshake carried the instance's `auth` credential (an `http` transport, the credential sent as a header), the refusal is a `ConnectorCredentialRejectedError` with status `403`. Its message names the missing tools and the tools the server does list for that credential, and it names both causes with the fix for each: give the credential the scopes those tools need and set it again, or fix `providerConfig.include`. The materializer handles it as it handles a `401` / `403`: the instance is degraded and the boot does not fail. A stored credential is marked `rejected` and held until it is set again; an environment or vault credential is retried on the backoff, so widening the token's scopes where it was issued recovers the instance without a restart.
 - **Unchanged.** An instance whose handshake carried no credential (no `auth`, an `api-key` sent as a query parameter, or a `stdio` transport) keeps the plain configuration fault, fatal at boot, with the same message as before.
+- **Where it reads.** The `sys_connector_credential.status` field description (`@objectstack/service-automation`) now names this second way a stored credential becomes `rejected`.
diff --git a/packages/services/service-automation/src/sys-connector-credential.object.ts b/packages/services/service-automation/src/sys-connector-credential.object.ts
index 1718dcdc6ac..cc0d25dfda7 100644
--- a/packages/services/service-automation/src/sys-connector-credential.object.ts
+++ b/packages/services/service-automation/src/sys-connector-credential.object.ts
@@ -104,7 +104,7 @@ export const SysConnectorCredential = ObjectSchema.create({
       required: true,
       defaultValue: 'set',
       description:
-        "`set` when a value is stored; `rejected` when an upstream refused it (an instance's materialization or call answered 401 / 403). Back to `set` only when the value is set again or a provider proves it while materializing (mcp); a call answered 2xx does not, since the endpoint may not check the credential. A reference no source answers for is `missing` in the listing and has no row.",
+        "`set` when a value is stored; `rejected` when an upstream refused it (an instance's materialization or call answered 401 / 403, or an MCP server it was sent to did not list a tool the instance's `include` names). Back to `set` only when the value is set again or a provider proves it while materializing (mcp); a call answered 2xx does not, since the endpoint may not check the credential. A reference no source answers for is `missing` in the listing and has no row.",
     }),
 
     status_reason: Field.textarea({
diff --git a/packages/spec/src/integration/connector-provider-errors.ts b/packages/spec/src/integration/connector-provider-errors.ts
index ca39a09c5b0..3618ae7f834 100644
--- a/packages/spec/src/integration/connector-provider-errors.ts
+++ b/packages/spec/src/integration/connector-provider-errors.ts
@@ -78,18 +78,30 @@ export function isConnectorUpstreamUnavailable(err: unknown): boolean {
  * message — never the value. A value from an environment variable or the
  * host's resolver can change where the process cannot see it, so its instance
  * is retried on the backoff.
+ *
+ * An upstream that accepts the credential but answers it with less than the
+ * instance declares is the same outcome: an MCP server that lists only the
+ * tools a credential may use, and so leaves out a tool the instance's
+ * `include` names, is answered with this marker by the `mcp` provider.
  */
 export const CONNECTOR_CREDENTIAL_REJECTED = 'CONNECTOR_CREDENTIAL_REJECTED' as const;
 
 /**
  * Thrown by a connector provider factory when the upstream it contacted to
- * materialize an instance refused the credential it sent (HTTP 401 / 403).
- * Carries {@link CONNECTOR_CREDENTIAL_REJECTED} as its `code` and the HTTP
- * status. ⛔ The message must not carry the credential.
+ * materialize an instance refused the credential it sent (HTTP 401 / 403), or
+ * accepted it and withheld what the instance declares (see
+ * {@link CONNECTOR_CREDENTIAL_REJECTED}). Carries
+ * {@link CONNECTOR_CREDENTIAL_REJECTED} as its `code` and the HTTP status.
+ * ⛔ The message must not carry the credential.
  */
 export class ConnectorCredentialRejectedError extends Error {
   readonly code = CONNECTOR_CREDENTIAL_REJECTED;
-  /** The upstream's HTTP status: 401 or 403. */
+  /**
+   * The upstream's HTTP status: 401 or 403. For an upstream that answered
+   * `2xx` and withheld what the instance declares, 403: the status a
+   * credential short of the scopes a resource needs is answered with
+   * (RFC 6750 §3.1, `insufficient_scope`).
+   */
   readonly status: number;
   /** The underlying failure, kept for diagnostics. */
   readonly cause?: unknown;

From c762819187821837c08e29807ac04817ec0e4c3e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 31 Oct 2026 05:28:17 +0000
Subject: [PATCH 4/7] docs(connector-github): an under-scoped token leaves
 github_mcp disconnected and the server starting

The Credentials paragraph said a classic token whose scopes hide an
included tool stops the server from starting when set as the environment
variable. The mcp provider now degrades the instance on either path. It
also notes that GitHub's server keeps read tools that work on public
repositories, these two among them, listed whatever the scopes.

Claude-Session: https://claude.ai/code/session_017xRBcVBKAFk1ntXSjvPt7U
Co-authored-by: Claude <noreply@anthropic.com>
---
 packages/apps/connector-github/README.md | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/packages/apps/connector-github/README.md b/packages/apps/connector-github/README.md
index 647963f0a72..24aa235aa15 100644
--- a/packages/apps/connector-github/README.md
+++ b/packages/apps/connector-github/README.md
@@ -34,13 +34,18 @@ install dialog right after installing. An environment variable named
 `GITHUB_MCP_TOKEN` on the server takes precedence over a stored value.
 
 Prefer a fine-grained token. With a classic token, GitHub's server hides every
-tool whose scope the token lacks. If that hides `search_issues` or
-`issue_read`, the connector does not start without them: a value set in
-**Connector Credentials** leaves `github_mcp` disconnected with a reason naming
-the missing tools, and a value set as the server environment variable stops the
-server from starting at all. Replace the token with one that carries the `repo`
-scope: a new value in **Connector Credentials** takes effect at once, a new
-environment variable at the next start.
+tool whose scope the token lacks, though it keeps read tools that also work on
+public repositories listed whatever the scopes, `search_issues` and
+`issue_read` among them ([PAT scope filtering](https://github.com/github/github-mcp-server/blob/main/docs/scope-filtering.md#public-repository-access)).
+If the server does leave out a tool this app includes, `github_mcp` stays
+disconnected with a reason naming the missing tools and both possible causes,
+the token's scopes or the app's declaration, and its flows fail; the server
+itself keeps starting, wherever the value is set. Replace the token with one
+that carries the `repo` scope: a new value in **Connector Credentials** takes
+effect at once, a new environment variable at the next start. Widening the
+scopes of the token you already use works too: set it again in **Connector
+Credentials**, or, for the environment variable, wait for the connector's next
+automatic retry, at most five minutes away.
 
 The token is only ever sent to GitHub. It is never stored in the app's
 metadata.

From a51f1291304649abc043081e9f440000728d236e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 31 Oct 2026 05:36:41 +0000
Subject: [PATCH 5/7] test(connector-mcp): a credential written into
 transport.headers keeps the declaration fault

Pins the boundary the plain branch's comment now states: only the instance's
auth takes the credential path; a header credential is part of the
declaration and is fixed by editing it.

Claude-Session: https://claude.ai/code/session_017xRBcVBKAFk1ntXSjvPt7U
Co-authored-by: Claude <noreply@anthropic.com>
---
 .../src/mcp-include-credential-scope.test.ts  | 19 +++++++++++++++++++
 .../connector-mcp/src/mcp-provider.ts         |  8 +++++---
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts b/packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts
index 15ae41a80ad..e883abc450a 100644
--- a/packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts
+++ b/packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts
@@ -135,6 +135,25 @@ describe('mcp provider: an include the server does not list for the credential i
         expect(server.state.closed).toBe(1);
     });
 
+    it('control: a credential written into transport.headers is part of the declaration — the plain fault, even when it filtered the list', async () => {
+        const server = scopedServer({ [NARROW_TOKEN]: ['whoami'] });
+        const factory = createMcpProviderFactory({ clientFactory: server.clientFactory });
+        const err = await thrownBy(() =>
+            factory(ctx({
+                providerConfig: {
+                    transport: { kind: 'http', url: URL, headers: { Authorization: `Bearer ${NARROW_TOKEN}` } },
+                    include: INCLUDE,
+                },
+            })),
+        );
+        expect(isConnectorCredentialRejected(err)).toBe(false);
+        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
+        expect((err as Error).message).toContain(
+            "providerConfig.include names 'search_invoices', 'read_invoice', which the MCP server does not list. Each entry",
+        );
+        expect((err as Error).message).toContain("the server lists 1 tool(s): 'whoami'.");
+    });
+
     it('control: a stdio instance with resolved auth keeps the plain fault — auth is not sent to a stdio server', async () => {
         const server = scopedServer({});
         const factory = createMcpProviderFactory({ clientFactory: server.clientFactory, declarativeStdio: true });
diff --git a/packages/connectors/connector-mcp/src/mcp-provider.ts b/packages/connectors/connector-mcp/src/mcp-provider.ts
index adfc23e431f..05b010b670d 100644
--- a/packages/connectors/connector-mcp/src/mcp-provider.ts
+++ b/packages/connectors/connector-mcp/src/mcp-provider.ts
@@ -353,9 +353,11 @@ export function createMcpProviderFactory(deps: McpProviderDeps = {}): ConnectorP
             403,
           );
         }
-        // No instance credential reached the server, so its list is not one
-        // filtered for a credential: a configuration fault, thrown plain —
-        // fatal at boot, a skipped entry on reload.
+        // The instance's `auth` did not reach the server, so its list was not
+        // filtered for a credential the administrator supplies; one written
+        // into `providerConfig.transport.headers` is part of the declaration,
+        // fixed by editing it. A configuration fault, thrown plain — fatal at
+        // boot, a skipped entry on reload.
         throw new Error(
           `connector-mcp provider: connector '${ctx.name}' providerConfig.include names ` +
             `${named}, which the MCP server does not list. ` +

From b6312fe6f3108fe588197fd5256ba041077789cf Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 31 Oct 2026 05:41:25 +0000
Subject: [PATCH 6/7] test(connector-mcp): read objectql, driver-sql and
 platform-objects from source in tests

The store-backed test imports the three; check:test-source-alias requires
an anchored source alias for each rather than a wider unaliased ledger. The
registry log is quieted through OS_REGISTRY_LOG.

Claude-Session: https://claude.ai/code/session_017xRBcVBKAFk1ntXSjvPt7U
Co-authored-by: Claude <noreply@anthropic.com>
---
 .../connectors/connector-mcp/vitest.config.ts | 35 +++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/packages/connectors/connector-mcp/vitest.config.ts b/packages/connectors/connector-mcp/vitest.config.ts
index 092f3349553..716c2dbe1e8 100644
--- a/packages/connectors/connector-mcp/vitest.config.ts
+++ b/packages/connectors/connector-mcp/vitest.config.ts
@@ -1,4 +1,35 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
-// This package needs nothing beyond the shared preset; see its header.
-export { default } from '../../../vitest.preset.mts';
+import { defineConfig } from 'vitest/config';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  test: {
+    // A late console.* must not redden a green suite (#10374): vitest's worker
+    // forwards console output over RPC and discards the promise, and a write
+    // landing after teardown's rpcDone() snapshot is rejected into an unhandled
+    // error — a fully green run that exits 1. Disarming removes the mechanism.
+    // Mechanism + measured costs: examples/app-showcase/vitest.config.ts.
+    // Enforced repo-wide by scripts/check-console-intercept-disarm.mjs.
+    disableConsoleIntercept: true,
+    // `mcp-include-credential-scope.test.ts` boots the credential store on a
+    // real ObjectQL, whose registry logs one line per registered item; quiet
+    // it through the engine's own `OS_REGISTRY_LOG` seam, not a change to its
+    // shipped default (scripts/check-registry-log-declared.mjs).
+    env: { OS_REGISTRY_LOG: 'warn' },
+  },
+  resolve: {
+    // The store-backed test reads these three from SOURCE, so its verdict is
+    // about the checkout, never about whatever `dist/` was last built
+    // (`pnpm check:test-source-alias`). Anchored, array form: a bare string
+    // key matches by prefix and would swallow the subpaths.
+    alias: [
+      { find: /^@objectstack\/driver-sql$/, replacement: path.resolve(HERE, '../../drivers/driver-sql/src/index.ts') },
+      { find: /^@objectstack\/objectql$/, replacement: path.resolve(HERE, '../../objectql/src/index.ts') },
+      { find: /^@objectstack\/platform-objects$/, replacement: path.resolve(HERE, '../../platform-objects/src/index.ts') },
+    ],
+  },
+});

From a91c84adc9210ce1edd29d87b42af40c96dbef70 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 1 Nov 2026 03:10:37 +0000
Subject: [PATCH 7/7] fix(connector-mcp): a grant-bearing instance's borrowed
 token keeps the plain include fault, pinned

main's MCP authorization flow hands an oauth2 / app-credential instance a
credential handle, and its discovery listing is answered for an
organization's borrowed token. That token does reach the server, but the
credential path a refusal takes holds and marks the instance's
credentialRef row, which for such an instance is its client secret, and a
reconnect of the same organization does not re-attempt the held instance.
So credentialSent stays the static-auth predicate, the comment says why,
one test pins it, and the docs and changeset name the grant-bearing kinds
among the instances that keep the plain fault.

Claude-Session: https://claude.ai/code/session_017xRBcVBKAFk1ntXSjvPt7U
Co-authored-by: Claude <noreply@anthropic.com>
---
 .../28311-mcp-include-scope-hidden-tools.md   |  2 +-
 content/docs/automation/connectors.mdx        | 11 +++++---
 .../src/mcp-include-credential-scope.test.ts  | 27 ++++++++++++++++++-
 .../connector-mcp/src/mcp-provider.ts         |  9 +++++++
 4 files changed, 43 insertions(+), 6 deletions(-)

diff --git a/.changeset/28311-mcp-include-scope-hidden-tools.md b/.changeset/28311-mcp-include-scope-hidden-tools.md
index a6c8773fdbc..5ec41be9448 100644
--- a/.changeset/28311-mcp-include-scope-hidden-tools.md
+++ b/.changeset/28311-mcp-include-scope-hidden-tools.md
@@ -12,5 +12,5 @@ Some MCP servers list only the tools the credential they are sent may use: GitHu
 
 - **Before.** When `providerConfig.include` named a tool the server did not list, the `mcp` provider refused with a plain configuration fault in every case. With the credential in an environment variable, the whole boot failed. With a credential stored through the credential door, the instance was degraded with a reason telling the administrator to fix the app's declaration.
 - **Now.** When the handshake carried the instance's `auth` credential (an `http` transport, the credential sent as a header), the refusal is a `ConnectorCredentialRejectedError` with status `403`. Its message names the missing tools and the tools the server does list for that credential, and it names both causes with the fix for each: give the credential the scopes those tools need and set it again, or fix `providerConfig.include`. The materializer handles it as it handles a `401` / `403`: the instance is degraded and the boot does not fail. A stored credential is marked `rejected` and held until it is set again; an environment or vault credential is retried on the backoff, so widening the token's scopes where it was issued recovers the instance without a restart.
-- **Unchanged.** An instance whose handshake carried no credential (no `auth`, an `api-key` sent as a query parameter, or a `stdio` transport) keeps the plain configuration fault, fatal at boot, with the same message as before.
+- **Unchanged.** An instance whose handshake carried no static credential (no `auth`, an `api-key` sent as a query parameter, a `stdio` transport, or a grant-bearing `oauth2` / `app-credential` instance, whose token is borrowed per request from an organization's connection) keeps the plain configuration fault, fatal at boot, with the same message as before.
 - **Where it reads.** The `sys_connector_credential.status` field description (`@objectstack/service-automation`) now names this second way a stored credential becomes `rejected`.
diff --git a/content/docs/automation/connectors.mdx b/content/docs/automation/connectors.mdx
index fa648077a07..0b6b436e714 100644
--- a/content/docs/automation/connectors.mdx
+++ b/content/docs/automation/connectors.mdx
@@ -251,8 +251,11 @@ tool names; any other shape (a string such as `include: 'web_search'`, an
 object) fails the boot before connecting, and never falls back to exposing
 every tool. An entry the server's `tools/list` does not carry — a typo, or a
 tool the server renamed or dropped — is never ignored: the refusal names the
-entry and lists the server's tools. On an instance that sends no credential it
-fails the boot. When the instance sends its `auth` credential, the entry may
+entry and lists the server's tools. On an instance that sends no static
+credential — no `auth`, an `api-key` sent as a query parameter, a `stdio`
+transport, or a grant-bearing `oauth2` / `app-credential` instance, whose token
+is borrowed per request — it fails the boot. When the instance sends a static
+`auth` credential (`bearer`, `basic`, or an `api-key` header), the entry may
 instead be a tool the server hides from that credential: some servers list
 only the tools a credential is allowed to use (GitHub's hides each tool a
 classic token's scopes do not cover), and the answer does not say what it hid.
@@ -777,11 +780,11 @@ retry):
 | `credentialRef` (or a `signed` instance's `vendorPublicKeyRef`) resolves to nothing | **Not fatal**: the instance registers **degraded**, naming the reference — set it (`PUT …/credential-refs/:ref`), and it materializes without a restart |
 | A `signed` reference resolves to something that is not a key of the scheme's kind (an `alipay-v3` key that is not RSA) | **Hard boot error** naming the instance and which reference cannot sign or verify, never the value |
 | A response to an `alipay-v3` call is unsigned (below status 400) or its signature does not verify | The dispatch **fails** naming the instance and the status; the response's body is never returned |
-| The upstream refuses the credential (`401` / `403`), or an `mcp` server sent the credential does not list a tool the instance's `include` names | **Not fatal**: the instance registers **degraded**. A stored credential is marked `rejected` and waits until it is set again (or a restart); an environment or vault credential is retried on the backoff |
+| The upstream refuses the credential (`401` / `403`), or an `mcp` server sent a static credential does not list a tool the instance's `include` names | **Not fatal**: the instance registers **degraded**. A stored credential is marked `rejected` and waits until it is set again (or a restart); an environment or vault credential is retried on the backoff |
 | Instance `name` collides with a plugin-registered connector | **Hard boot error** — there is no silent precedence between the two worlds |
 | stdio transport without host opt-in | **Hard boot error** with the `declarativeStdio` fix inline — a security rejection is never retried |
 | MCP server unreachable / `tools/list` fails; remote spec URL unreachable or transiently failing (408/429/5xx) | **Not fatal**: the instance registers **degraded** (visible on `GET /api/v1/automation/connectors` with the reason), dispatches fail with that reason, and the platform retries on a 5s→5min backoff — recovery is automatic |
-| A retry of a degraded instance reaches the upstream and meets a configuration fault (an `include` naming a tool or operation the upstream does not offer; on an `mcp` instance that sends a credential, the credential row above applies instead) | **Not fatal**: the instance stays **degraded**, now with the configuration reason, and is **not retried** — dispatches fail saying to edit its declaration; an edit of the entry (or a restart) re-attempts it |
+| A retry of a degraded instance reaches the upstream and meets a configuration fault (an `include` naming a tool or operation the upstream does not offer; on an `mcp` instance that sends a static credential, the credential row above applies instead) | **Not fatal**: the instance stays **degraded**, now with the configuration reason, and is **not retried** — dispatches fail saying to edit its declaration; an edit of the entry (or a restart) re-attempts it |
 | Wrong spec URL (other 4xx) or unparseable document | Configuration fault — **hard boot error** |
 | A `connector_action` input that, once evaluated, breaks the action's `inputSchema` (a missing `required` parameter, a wrong `type`) | **The step fails before dispatch** with `VALIDATION_ERROR`, naming each parameter path, and nothing is sent; a `fault` edge or `try_catch` can route it. Supply the parameter or send the declared type: text is never converted, so cast it in a CEL envelope (`int()`, `double()`, `bool()`). `GET /api/v1/automation/connectors` lists the schema; `os validate` does not judge the input against the `inputSchema` yet |
 | A bad entry arrives via **runtime reload** (a Studio publish, a direct active save through `PUT /api/v1/meta/connector/:name`, or a delete, made on any replica — peers reconcile on [cluster lane 2](/docs/kernel/cluster#62-the-cluster-invalidation-family); or a dev reload) | Logged and **skipped**, never crashing the live server; a changed instance's old connector keeps serving until its replacement materializes |
diff --git a/packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts b/packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts
index e883abc450a..6644c08d3d3 100644
--- a/packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts
+++ b/packages/connectors/connector-mcp/src/mcp-include-credential-scope.test.ts
@@ -27,7 +27,7 @@ import { SqlDriver } from '@objectstack/driver-sql';
 import { SysSecret } from '@objectstack/platform-objects';
 import { AutomationServicePlugin, type AutomationEngine } from '@objectstack/service-automation';
 import type { CryptoContext, CryptoHandle, ICryptoProvider } from '@objectstack/spec/contracts';
-import type { ConnectorProviderContext } from '@objectstack/spec/integration';
+import type { ConnectorCredentialHandle, ConnectorProviderContext } from '@objectstack/spec/integration';
 import { isConnectorCredentialRejected, isConnectorUpstreamUnavailable } from '@objectstack/spec/integration';
 import type { McpClientLike, McpToolDescriptor, McpTransport } from './mcp-connector.js';
 import { ConnectorMcpPlugin } from './connector-mcp-plugin.js';
@@ -167,6 +167,31 @@ describe('mcp provider: an include the server does not list for the credential i
         expect((err as Error).message).toContain("providerConfig.include names 'nope', which the MCP server does not list.");
     });
 
+    it('an oauth2 instance (a credential handle) keeps the plain fault: its token is borrowed per request, not the instance auth', async () => {
+        // The listing is answered for the borrowed token, but the credential
+        // path's hold and mark are keyed to the instance's credentialRef row
+        // (an oauth2 instance's client secret), so the provider does not
+        // route this case there. See the comment on `credentialSent`.
+        const server = scopedServer({}, ['whoami']);
+        const handle: ConnectorCredentialHandle = {
+            connector: 'vendor_mcp',
+            async get() { return { auth: { type: 'bearer', token: NARROW_TOKEN } }; },
+            async refresh() { return { auth: { type: 'bearer', token: NARROW_TOKEN } }; },
+        };
+        const factory = createMcpProviderFactory({ clientFactory: server.clientFactory });
+        const err = await thrownBy(() => factory(ctx({ credentialHandle: handle })));
+        expect(isConnectorCredentialRejected(err)).toBe(false);
+        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
+        expect((err as Error).message).toMatch(
+            /^connector-mcp provider: connector 'vendor_mcp' providerConfig\.include names 'search_invoices', 'read_invoice', which the MCP server does not list\. Each entry/,
+        );
+        // The discovery session was opened through the borrowing fetch, with no static header.
+        const [discovery] = server.state.connects;
+        expect(discovery.kind === 'http' && typeof discovery.fetch).toBe('function');
+        expect(discovery.kind === 'http' && discovery.headers?.Authorization).toBeFalsy();
+        expect(server.state.closed).toBe(1);
+    });
+
     it('control: a credential whose listing carries every entry materializes exactly those tools, proven', async () => {
         const server = scopedServer({ [WIDE_TOKEN]: TOOLS.map((t) => t.name) });
         const mat = await createMcpProviderFactory({ clientFactory: server.clientFactory })(
diff --git a/packages/connectors/connector-mcp/src/mcp-provider.ts b/packages/connectors/connector-mcp/src/mcp-provider.ts
index 2bcb08c2a79..e81da0238e3 100644
--- a/packages/connectors/connector-mcp/src/mcp-provider.ts
+++ b/packages/connectors/connector-mcp/src/mcp-provider.ts
@@ -457,6 +457,15 @@ export function createMcpProviderFactory(deps: McpProviderDeps = {}): ConnectorP
     // [#27237] The handshake carried the instance's credential only over
     // http, and only as a header (an api-key `paramName` is not sent): then
     // the server's answer was given to that credential.
+    //
+    // A grant-bearing instance's borrowed token (`ctx.credentialHandle`)
+    // reaches the server too, and is deliberately not counted here: the
+    // credential path a refusal below takes holds and marks the instance's
+    // `credentialRef` row, which for such an instance is its client secret —
+    // a value the listing never depended on — while the token that was sent
+    // belongs to an organization's connection, which that path neither marks
+    // nor re-attempts on a reconnect. Until the materializer has a route for
+    // it, such an instance keeps the plain fault.
     const credentialSent = transport.kind === 'http' && sendsInstanceAuth(ctx.auth);
     if (includeList) {
       // An entry naming a tool the server does not list is refused after the