@@ -0,0 +1,13 @@
+---
+'@objectstack/mcp': patch
+'@objectstack/runtime': patch
+---
+
+feat(mcp): a host can observe and refuse every MCP tool call through one neutral interceptor on the `mcp` service
+
+Clause-②: yes (widening) — `MCPServerRuntime` gains `setToolInterceptor`, `clearToolInterceptor` and `hasToolInterceptor`, `handleHttpRequest` gains an optional `caller`, and `@objectstack/mcp` exports the types `McpToolInterceptor`, `McpToolCallContext`, `McpToolCallPrincipal`, `McpToolCallRefusal`, `McpToolCallResult`, `McpToolTransport`, `McpPrincipalKind`, `McpCallerExecutionContext` and `McpHttpCaller`. With no interceptor installed, every tool call answers exactly as before.
+Metadata-protocol: none
+
+- **`@objectstack/mcp`:** `runtime.setToolInterceptor(fn)` installs one interceptor (a single slot, read at each call) around every tool call on both transports: the object, action, file and federation tools, the host-injected authoring family, the bridged AI tools, and any tool a plugin registers on the runtime's server. The interceptor receives a frozen context built on the server side — `door: 'mcp'`, `transport` (`http` or `stdio`), the tool name, a copy of the validated arguments, and the principal (`userId`, `principalKind`, `onBehalfOf`, `performedBy.clientId`, `organizationId`, `environmentId`, and `isSystem` for a system caller) projected from the host's resolved `ExecutionContext`, never from a request header. It allows by calling `next()` (and may return a replacement result), or denies by returning `{ outcome: 'deny', code, message, status }`, which the client receives in the coded-refusal envelope every MCP tool error uses. A throw from the interceptor refuses the call the same way; any other verdict is refused as `500 INTERNAL_ERROR`. The package holds no policy: audit, seat checks and kill switches belong to whichever host installs the interceptor.
+- **`@objectstack/mcp`, stdio:** once the plugin has resolved `OS_MCP_STDIO_API_KEY`, the AI tools it bridges from the AI service's tool registry run with that key's user as their execution context (`actor`: id, positions, permissions), resolved per call, so a registry that needs an actor no longer refuses them as unauthenticated, and a key that stops resolving refuses the next call. A runtime with no stdio principal bound calls the registry exactly as before.
+- **`@objectstack/runtime`:** the `/mcp` dispatcher passes the request's resolved `ExecutionContext` and the environment it dispatched for to `handleHttpRequest` as `caller`, the input an interceptor's principal is projected from.
@@ -219,7 +219,7 @@ One of the largest consumers of the flag;
 
 ### 6. Reads that only carry the flag onward
 
-Not behaviours: these three sites read the flag solely to copy it into another
+Not behaviours: these four sites read the flag solely to copy it into another
 context or envelope. They are listed because the census counts them, and because
 a reader tracing where elevation travels needs them.
 
@@ -228,6 +228,7 @@ a reader tracing where elevation travels needs them.
 | 63 | `buildSession` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
 | 64 | `isSystem` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
 | 65 | `executionContextFromHook` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |
+| 66 | `toolCallPrincipalOf` | mcp | Projects the host's resolved `ExecutionContext` into the frozen principal an installed MCP tool-call interceptor reads, carrying `isSystem: true` only for a system caller. It decides nothing: the tool still runs under its own context |
 
 ---
 
@@ -397,7 +398,7 @@ restates none of its figures:
 | Of those reads: reads of one of the unrelated metadata fields | subtracted — the collision this page opens with |
 | Of those reads: reads of `ExecutionContext.isSystem` | **the census answer**: every one sits in a symbol a row above names |
 | — behaviour-bearing (rows 1–62 above) | sections 1 to 5 |
-| — carry the flag onward only (rows 63–65 above) | section 6 |
+| — carry the flag onward only (rows 63–66 above) | section 6 |
 
 `node scripts/isystem-census.mjs` prints how many appearances fell in each
 syntactic slot, the subtraction, the answer and the packages and files that
@@ -532,6 +533,7 @@ and CI refuses one that differs from what the tree produces.
 |:---|--:|:---|
 | `packages/core/src/security/anonymous-deny.ts#shouldDenyAnonymous` | 1 | 10 |
 | `packages/mcp/src/stdio-data-bridge.ts#enforceApiExposure` | 1 | 15 |
+| `packages/mcp/src/tool-call-interceptor.ts#toolCallPrincipalOf` | 2 | 66 |
 | `packages/metadata-core/src/meta-write-capability.ts#metaWriteCapabilityVerdict` | 1 | 51 |
 | `packages/metadata-core/src/meta-write-capability.ts#walledCatalogWriteVerdict` | 1 | 55b |
 | `packages/metadata-core/src/object-schema-fls.ts#isObjectSchemaMaskExempt` | 1 | 8 |
 
@@ -33,7 +33,11 @@
 // `accessToken: authz.accessToken`.
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
 import type { ExecutionContext } from '@objectstack/spec/kernel';
+import type { AIToolDefinition, ToolCallPart, ToolExecutionContext } from '@objectstack/spec/contracts';
+import type { McpToolCallContext } from '../types.js';
 
 /** The resolved envelope the API key stands for — the input this face converts. */
 const AUTHZ = {
@@ -77,7 +81,7 @@ interface FindCall {
   options: { context?: ExecutionContext; where?: unknown; limit?: number };
 }
 
-function createHarness() {
+function createHarness(extraServices: Record<string, unknown> = {}) {
   const finds: FindCall[] = [];
   const ql = {
     find: vi.fn(async (object: string, options: FindCall['options']) => {
@@ -99,7 +103,7 @@ function createHarness() {
     unregister: vi.fn(),
   };
   const settings = { get: vi.fn(async () => undefined) };
-  const services: Record<string, unknown> = { objectql: ql, metadata, settings };
+  const services: Record<string, unknown> = { objectql: ql, metadata, settings, ...extraServices };
   const ctx = {
     registerService: vi.fn(),
     getService: vi.fn((name: string) => {
@@ -260,3 +264,66 @@ describe('#7279 — stdio ExecutionContext, assembled by the shared assembler',
     await expect(getRecord('crm_account', 'r_1')).rejects.toThrow(/no longer valid/);
   });
 });
+
+describe('[#31605] the stdio principal reaches the bridged AI tools and the tool-call interceptor', () => {
+  const originalEnv = { ...process.env };
+  const AI_TOOL: AIToolDefinition = {
+    name: 'summarize_pipeline',
+    description: 'Summarize the open pipeline.',
+    parameters: { type: 'object', properties: {} },
+  };
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    process.env.OS_MCP_STDIO_API_KEY = 'osk_test';
+    resolveAuthzContextMock.mockClear();
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('a bridged tool runs as the key\'s user, and an interceptor is told that user, re-resolved per call', async () => {
+    const executed: Array<{ call: ToolCallPart; context?: ToolExecutionContext }> = [];
+    const toolRegistry = {
+      getAll: () => [AI_TOOL],
+      async execute(call: ToolCallPart, context?: ToolExecutionContext) {
+        executed.push({ call, context });
+        return { type: 'tool-result', toolCallId: call.toolCallId, toolName: call.toolName, output: { type: 'text', value: 'ok' } };
+      },
+    };
+    const { ctx } = createHarness({ ai: { toolRegistry } });
+    await startStdio(ctx);
+    const runtime = (ctx.registerService.mock.calls.find((c: unknown[]) => c[0] === 'mcp') as unknown[])[1] as InstanceType<
+      typeof MCPServerRuntime
+    >;
+    const seen: McpToolCallContext[] = [];
+    runtime.setToolInterceptor(async (call, next) => {
+      seen.push(call);
+      return next();
+    });
+
+    const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
+    await runtime.server.connect(serverSide);
+    const client = new Client({ name: 'stdio-principal-pin', version: '0.0.0' });
+    await client.connect(clientSide);
+    const before = resolveAuthzContextMock.mock.calls.length;
+    try {
+      const answer = await client.callTool({ name: 'summarize_pipeline', arguments: {} });
+      expect(answer.isError).toBeFalsy();
+    } finally {
+      await client.close();
+    }
+
+    expect(executed).toHaveLength(1);
+    expect(executed[0]!.context).toEqual({
+      actor: { id: 'u_stdio', positions: ['sales_rep'], permissions: ['records:read'] },
+    });
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toMatchObject({ door: 'mcp', transport: 'stdio', toolName: 'summarize_pipeline' });
+    expect(seen[0]!.principal).toEqual({ userId: 'u_stdio', principalKind: 'human', organizationId: 'org_stdio' });
+    // Once for the interceptor's principal, once for the tool's context: the
+    // identity is never cached across calls (ADR-0101 D1).
+    expect(resolveAuthzContextMock.mock.calls.length - before).toBe(2);
+  });
+});
@@ -13,7 +13,7 @@
 export { MCPServerPlugin } from './plugin.js';
 export type { MCPServerPluginOptions } from './plugin.js';
 export { MCPServerRuntime } from './mcp-server-runtime.js';
-export type { MCPServerRuntimeConfig } from './mcp-server-runtime.js';
+export type { MCPServerRuntimeConfig, McpHttpCaller } from './mcp-server-runtime.js';
 // [#26464] The host-injected authoring bridge behind `metadata:write`: the
 // shapes a host passes to `handleHttpRequest` (`authoring`) and the door
 // constant its access check branches on.
@@ -25,6 +25,19 @@ export type {
   McpAuthoringToolRegistry,
   McpAuthoringInjection,
 } from './types.js';
+// [#31605] The host-installed tool-call interceptor
+// (`MCPServerRuntime.setToolInterceptor`): what it is told about each call,
+// and the verdicts it may return.
+export type {
+  McpToolInterceptor,
+  McpToolCallContext,
+  McpToolCallPrincipal,
+  McpToolCallRefusal,
+  McpToolCallResult,
+  McpToolTransport,
+  McpPrincipalKind,
+} from './types.js';
+export type { McpCallerExecutionContext } from './tool-call-interceptor.js';
 export {
   registerObjectTools,
   registerActionTools,
 
@@ -524,8 +524,12 @@ function errorResultFromThrown(err: unknown, request: string, objectName?: strin
  * The runtime dispatcher drops those `details` from the wire, so serving them
  * here would disclose on MCP what REST withholds. `code`, `message` and
  * `status` are what every boundary serves.
+ *
+ * [#31605] Exported for the tool-call interceptor, which answers a throw from
+ * a host's interceptor as the tools' own catches answer one; not on the
+ * package entry.
  */
-function errorResultWithCode(err: unknown) {
+export function errorResultWithCode(err: unknown) {
   const envelope = thrownRefusalEnvelope(err);
   return envelope ? codedErrorResult({ ...envelope }) : errorResult(messageOf(err));
 }
@@ -813,7 +817,14 @@ function landedWriteResultOrError(
   return textResult(earned);
 }
 
-function codedErrorResult(error: {
+/**
+ * The coded-refusal envelope every MCP tool error with a code answers with:
+ * `isError: true`, text `{ "error": { code, message, status, … } }`.
+ * [#31605] Exported for the tool-call interceptor's refusal
+ * (`tool-call-interceptor.ts`), so a host's deny reaches the client in the
+ * envelope the tools' own refusals use; not on the package entry.
+ */
+export function codedErrorResult(error: {
   code?: string;
   message: string;
   status?: number;