:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(mcp): hide and refuse mcp tools a scout run does not hold (#115824)
posthog[bot]a493c56f99ee
diff --git a/docs/published/handbook/engineering/ai/sandboxed-agents.md b/docs/published/handbook/engineering/ai/sandboxed-agents.mdindex f511ad9d37c0..3833303b4fd0 100644--- a/docs/published/handbook/engineering/ai/sandboxed-agents.md+++ b/docs/published/handbook/engineering/ai/sandboxed-agents.md@@ -254,6 +254,8 @@ The write path is gated by `scouts-tool-access` and fails closed when the flag iWhile the flag is on, a run stamps the list on its task at dispatch, and a config edit applies from the next run.The run holds the listed tools, the built-in run-context tools, and the tools the MCP server offers every client.+The run-context tools include `skill-get` and `skill-file-get`, so even an empty selection can load its skill and reference files without granting skill writes.+The tool catalogue returns `run_context_tools` for the picker’s always-available group. The picker excludes these from choices and removes redundant entries from saved lists when editing them.The API refuses a request that uses a method other than GET, HEAD, or OPTIONS, or that needs a write scope, unless a tool the run holds calls that endpoint or the endpoint belongs to the sandbox harness.The method counts because some actions change state behind a read scope.Harness run writes and run-context writes are restricted to the token-bound task’s current run.@@ -262,8 +264,10 @@ For soft-delete endpoints, updating an object does not grant deletion, and a delA narrowed run cannot call external MCP server tools or change tool approvals through the MCP Store endpoints.The refusal is a 403 with the code `scout_tool_not_granted`.The check reads the run from the token's task binding, never from a request header.-GET reads stay governed by the token scopes, and the MCP server still lists every tool the scopes allow.-Keep the flag disabled for customers until the MCP server hides unpicked tools and the settings picker ships.+GET reads stay governed by the token scopes.+Token introspection supplies the dispatch snapshot to the MCP server, which hides unpicked tools and refuses direct and exec calls with `tool_not_granted`.+Refused exec calls retain the catalogued target tool name in analytics; unknown names are recorded as `unrecognized`.+Keep the flag disabled for customers until the settings picker ships.### Activity attributiondiff --git a/posthog/api/oauth/views.py b/posthog/api/oauth/views.pyindex 1278c90cc766..3e011242d043 100644--- a/posthog/api/oauth/views.py+++ b/posthog/api/oauth/views.py@@ -2396,6 +2396,7 @@ def _active_access_token_response(scoped_teams: list[int],scoped_organizations: list[str],application: OAuthApplication | None,+ sandbox_task_id: uuid.UUID | None = None,) -> JsonResponse:"""RFC 7662 response for an active access token, whether it is stored or a signed JWT."""data: dict[str, Any] = {@@ -2410,6 +2411,16 @@ def _active_access_token_response(if application:data["client_id"] = application.client_iddata["client_name"] = application.name+ if sandbox_task_id is not None:+ # The policy resolves API routes, which import these views.+ from products.signals.backend.facade.tool_policy import resolve_scout_held_tools # noqa: PLC0415++ data["sandbox_task_id"] = str(sandbox_task_id)+ # The MCP server hides and refuses every tool outside this list. The API enforces the+ # same list per operation, so a client that ignores it gains nothing.+ held_tools = resolve_scout_held_tools(sandbox_task_id=sandbox_task_id)+ if held_tools is not None:+ data["mcp_allowed_tools"] = sorted(held_tools)return JsonResponse(data)@@ -2621,6 +2632,7 @@ class OAuthIntrospectTokenView(ClientProtectedScopedResourceView):scoped_teams=access_token.scoped_teams or [],scoped_organizations=access_token.scoped_organizations or [],application=access_token.application,+ sandbox_task_id=access_token.sandbox_task_id,)# Fall back to refresh token (lookup by plaintext token — OAuthRefreshToken hasdiff --git a/products/signals/backend/facade/tool_policy.py b/products/signals/backend/facade/tool_policy.pyindex 59e00832a0b9..8dad1d4b6343 100644--- a/products/signals/backend/facade/tool_policy.py+++ b/products/signals/backend/facade/tool_policy.py@@ -1,4 +1,5 @@from products.signals.backend.scout_harness.tool_policy import (TOOL_NOT_GRANTED_CODE as TOOL_NOT_GRANTED_CODE,+ resolve_scout_held_tools as resolve_scout_held_tools,scout_tool_denial as scout_tool_denial,)diff --git a/products/signals/backend/scout_harness/prompt.py b/products/signals/backend/scout_harness/prompt.pyindex c4b8fe438dd6..db215d9016e3 100644--- a/products/signals/backend/scout_harness/prompt.py+++ b/products/signals/backend/scout_harness/prompt.py@@ -879,7 +879,7 @@ _WRITE_ACCESS_OBJECTS: dict[str, str] = {_NARROWED_TOOLS_SECTION = """# Your tools-This scout's owner picked the PostHog MCP tools it may use. A write through a tool that was not picked comes back refused with `scout_tool_not_granted`. That refusal is final: do not retry it under another tool name or through the API. Say in your close-out what you could not do."""+This scout's owner picked the PostHog MCP tools it may use. A tool that was not picked comes back refused with `tool_not_granted`, and an API write outside those tools comes back with `scout_tool_not_granted`. These refusals are final: do not retry under another tool name or through the API. Say in your close-out what you could not do."""def _write_access_section(write_scopes: Sequence[str]) -> str:diff --git a/products/signals/backend/scout_harness/serializers.py b/products/signals/backend/scout_harness/serializers.pyindex 5d70c2437419..e0c713c440c6 100644--- a/products/signals/backend/scout_harness/serializers.py+++ b/products/signals/backend/scout_harness/serializers.py@@ -4661,6 +4661,9 @@ class ScoutToolCatalogueSerializer(serializers.Serializer):help_text=("Every catalogued MCP tool, ordered by name. Tools that a successor has replaced are left out."),)tool_presets = ScoutToolPresetSerializer(many=True, help_text="Tool selections expanded and validated on save.")+ run_context_tools = serializers.SerializerMethodField(+ help_text="Tools every scout run holds. Show these as always available, excluding them from saved selections."+ )presets = ScoutScopePresetSerializer(many=True,help_text="The scope presets a scout run can be dispatched with, and the scopes each one resolves to.",@@ -4673,6 +4676,10 @@ class ScoutToolCatalogueSerializer(serializers.Serializer):),)+ @extend_schema_field(serializers.ListField(child=serializers.CharField()))+ def get_run_context_tools(self, _obj: object) -> list[str]:+ return sorted(SCOUT_RUN_CONTEXT_TOOLS)+# --- Members (reviewer routing) --------------------------------------------diff --git a/products/signals/backend/scout_harness/tool_catalogue.py b/products/signals/backend/scout_harness/tool_catalogue.pyindex 31a16edc885b..4ffa96ccf2b4 100644--- a/products/signals/backend/scout_harness/tool_catalogue.py+++ b/products/signals/backend/scout_harness/tool_catalogue.py@@ -50,6 +50,8 @@ def scout_tool_access_enabled(team: Team) -> bool:SCOUT_RUN_CONTEXT_TOOLS = frozenset({+ "skill-get",+ "skill-file-get","scout-emit-report","scout-edit-report","scout-emit-signal",diff --git a/products/signals/backend/scout_harness/tool_policy.py b/products/signals/backend/scout_harness/tool_policy.pyindex d32c3c170c60..6e9764ec18b0 100644--- a/products/signals/backend/scout_harness/tool_policy.py+++ b/products/signals/backend/scout_harness/tool_policy.py@@ -66,6 +66,11 @@ SANDBOX_HARNESS_OPERATIONS: tuple[McpToolApiOperation, ...] = tuple(TOOL_NOT_GRANTED_CODE = "scout_tool_not_granted"+def resolve_scout_held_tools(*, sandbox_task_id: UUID) -> frozenset[str] | None:+ allowlist = tasks_facade.mcp_tool_allowlist_for_task(sandbox_task_id)+ return scout_held_mcp_tools(allowlist) if allowlist is not None else None++def scout_tool_denial(*, sandbox_task_id: UUID, view: Any, method: str, path: str, required_scopes: Iterable[str], data: Any = None) -> str | None:@@ -75,10 +80,9 @@ def scout_tool_denial("""if method.upper() in SAFE_METHODS and all(scope.endswith(":read") for scope in required_scopes):return None- allowlist = tasks_facade.mcp_tool_allowlist_for_task(sandbox_task_id)- if allowlist is None:+ held_tools = resolve_scout_held_tools(sandbox_task_id=sandbox_task_id)+ if held_tools is None:return None- held_tools = scout_held_mcp_tools(allowlist)for operation in _permitted_operations(held_tools):if not request_matches_operation(view=view, method=method, path=path, operation=operation):continuediff --git a/products/signals/backend/test/test_scout_harness_api.py b/products/signals/backend/test/test_scout_harness_api.pyindex a112e05347b5..44091c1a4537 100644--- a/products/signals/backend/test/test_scout_harness_api.py+++ b/products/signals/backend/test/test_scout_harness_api.py@@ -4928,6 +4928,17 @@ class TestScoutHarnessToolCatalogueAPI(APIBaseTest):assert not superseded & set(self._tools())+ def test_catalogue_context_tools_can_be_removed_from_a_saved_selection_before_editing(self) -> None:+ body = self.client.get(self._url()).json()+ selected = ["skill-get", "skill-file-get", "dashboard-update"]+ serializer = SignalScoutConfigUpdateSerializer(+ data={"allowed_mcp_tools": [name for name in selected if name not in body["run_context_tools"]]},+ partial=True,+ )++ assert serializer.is_valid(), serializer.errors+ assert serializer.validated_data["allowed_mcp_tools"] == ["dashboard-update"]+def test_reports_what_a_scout_would_have_to_be_granted(self) -> None:# `holdable` has to be measured against the scout postures, not against the full MCP scope# set: a picker built on the wrong set offers tools a scout is refused for at call time.diff --git a/products/signals/backend/test/test_scout_tool_policy.py b/products/signals/backend/test/test_scout_tool_policy.pyindex 79e3241c92fa..67f98ee4d673 100644--- a/products/signals/backend/test/test_scout_tool_policy.py+++ b/products/signals/backend/test/test_scout_tool_policy.py@@ -189,6 +189,22 @@ class TestScoutToolPolicyAPI(APIBaseTest):if expected_status == status.HTTP_403_FORBIDDEN:assert response.json()["code"] == "scout_tool_not_granted"+ @parameterized.expand([("empty", []), ("custom", ["insight-query"]), ("unrestricted", None)])+ def test_introspection_preserves_skill_bootstrap(self, _name: str, allowlist: list[str] | None) -> None:+ task = self._scout_client(allowlist=allowlist)++ response = self.client.post("/oauth/introspect/", {"token": "pha_synthetic_scout"}, format="json")++ body = response.json()+ assert body["active"] is True, body+ assert body["sandbox_task_id"] == str(task.id)+ if allowlist is None:+ assert "mcp_allowed_tools" not in body+ else:+ assert {"skill-get", "skill-file-get", *allowlist} <= set(body["mcp_allowed_tools"])+ assert "skill-update" not in body["mcp_allowed_tools"]+ assert "conversations-tickets-reply-create" not in body["mcp_allowed_tools"]+class TestScoutToolOperations(SimpleTestCase):@parameterized.expand([("notebooks-run",), ("notebooks-run-status",)])diff --git a/products/signals/frontend/generated/api.schemas.ts b/products/signals/frontend/generated/api.schemas.tsindex 53ffc20b5633..3499ff457eec 100644--- a/products/signals/frontend/generated/api.schemas.ts+++ b/products/signals/frontend/generated/api.schemas.ts@@ -5695,6 +5695,8 @@ export interface ScoutToolCatalogueApi {tools: ScoutToolCatalogueEntryApi[]/** Tool selections expanded and validated on save. */tool_presets: ScoutToolPresetApi[]+ /** Tools every scout run holds. Show these as always available, excluding them from saved selections. */+ readonly run_context_tools: readonly string[]/** The scope presets a scout run can be dispatched with, and the scopes each one resolves to. */presets: ScoutScopePresetApi[]/** The write scopes a person can grant to one scout from its settings. A scope outside this set can never be added to a scout's token. */diff --git a/products/signals/frontend/inbox/components/config/scouts/ScoutToolsPicker.tsx b/products/signals/frontend/inbox/components/config/scouts/ScoutToolsPicker.tsxindex f8374dbd7b87..e7394453af8a 100644--- a/products/signals/frontend/inbox/components/config/scouts/ScoutToolsPicker.tsx+++ b/products/signals/frontend/inbox/components/config/scouts/ScoutToolsPicker.tsx@@ -36,9 +36,10 @@ export function ScoutToolsPicker({ scoutName, savedTools, onSave, onClose }: Scoconst { catalogue, catalogueLoading, catalogueFailed } = useValues(scoutToolCatalogueLogic)const { loadCatalogue } = useActions(scoutToolCatalogueLogic)const [selected, setSelected] = useState<string[]>([...(savedTools ?? [])])+ const selectedTools = catalogue ? selected.filter((tool) => !catalogue.run_context_tools.includes(tool)) : selected// Set only while the draft is exactly a preset someone picked, so the save names the preset.const [preset, setPreset] = useState<ToolPresetEnumApi | null>(null)- const edited = preset !== null || [...selected].sort().join() !== [...(savedTools ?? [])].sort().join()+ const edited = preset !== null || [...selectedTools].sort().join() !== [...(savedTools ?? [])].sort().join()// Moving from all tools to a list is a change even when the list is still empty.const changed = edited || savedTools === null@@ -47,7 +48,7 @@ export function ScoutToolsPicker({ scoutName, savedTools, onSave, onClose }: Scobody = (<ToolCatalogueBodycatalogue={catalogue}- selected={selected}+ selected={selectedTools}preset={preset}onChange={(tools, nextPreset = null) => {setSelected(tools)@@ -91,7 +92,7 @@ export function ScoutToolsPicker({ scoutName, savedTools, onSave, onClose }: Scotype="primary"disabledReason={!catalogue ? 'Loading tools' : !changed ? 'No changes to save' : undefined}onClick={() => {- onSave(preset ? { tool_preset: preset } : { allowed_mcp_tools: [...selected].sort() })+ onSave(preset ? { tool_preset: preset } : { allowed_mcp_tools: [...selectedTools].sort() })}}data-attr="scout-tools-save">@@ -206,7 +207,7 @@ function ToolCatalogueBody({<div className="flex flex-col gap-1"><span className="text-[11px] font-medium uppercase tracking-wide text-muted">Always available</span><span className="text-xs text-secondary">- Every scout run can use these to report findings and keep its memory.+ Every scout run can use these to load skills, report findings, and keep its memory.</span><div className="flex flex-wrap gap-1">{alwaysHeld.map((label) => (diff --git a/products/signals/frontend/inbox/components/config/scouts/ScoutToolsSection.test.tsx b/products/signals/frontend/inbox/components/config/scouts/ScoutToolsSection.test.tsxindex 5dceba7bb5ad..f805aa79f733 100644--- a/products/signals/frontend/inbox/components/config/scouts/ScoutToolsSection.test.tsx+++ b/products/signals/frontend/inbox/components/config/scouts/ScoutToolsSection.test.tsx@@ -49,6 +49,9 @@ describe('ScoutToolsSection', () => {fireEvent.click(screen.getByText('Chosen tools'))expect(await screen.findByText('Get insight')).toBeInTheDocument()+ expect(screen.getByText('Get skill')).toBeInTheDocument()+ expect(screen.getByText('Get skill file')).toBeInTheDocument()+ expect(screen.queryByLabelText(/Get skill/)).not.toBeInTheDocument()expect(onUpdate).not.toHaveBeenCalled()})@@ -84,4 +87,20 @@ describe('ScoutToolsSection', () => {expect(onUpdate).not.toHaveBeenCalled()})++ it.each([+ ['an empty list', []],+ ['a saved list with bootstrap reads', ['skill-get', 'skill-file-get', 'insight-get']],+ ])('edits %s without submitting always-held tools', async (_name, savedTools) => {+ const onUpdate = renderSection({ allowed_mcp_tools: savedTools })+ fireEvent.click(screen.getByText('Edit tools'))+ await screen.findByText('Update dashboard')++ fireEvent.click(screen.getByText('Update dashboard'))+ fireEvent.click(screen.getByText('Save tools'))++ expect(onUpdate).toHaveBeenCalledWith('config-1', {+ allowed_mcp_tools: savedTools.length ? ['dashboard-update', 'insight-get'] : ['dashboard-update'],+ })+ })})diff --git a/products/signals/frontend/inbox/components/config/scouts/scoutToolFixtures.ts b/products/signals/frontend/inbox/components/config/scouts/scoutToolFixtures.tsindex 675803fbf01a..8cad3108d506 100644--- a/products/signals/frontend/inbox/components/config/scouts/scoutToolFixtures.ts+++ b/products/signals/frontend/inbox/components/config/scouts/scoutToolFixtures.ts@@ -29,6 +29,8 @@ function tool(/** A small catalogue with read, write, unavailable, and run context tools, for tests and stories. */export const SCOUT_TOOL_CATALOGUE: ScoutToolCatalogueApi = {tools: [+ tool('skill-get', 'Get skill', 'Skills'),+ tool('skill-file-get', 'Get skill file', 'Skills'),tool('dashboard-get', 'Get dashboard', 'Dashboards', { required_scopes: ['dashboard:read'] }),tool('dashboard-update', 'Update dashboard', 'Dashboards', {required_scopes: ['dashboard:write'],@@ -63,5 +65,6 @@ export const SCOUT_TOOL_CATALOGUE: ScoutToolCatalogueApi = {},],presets: [],+ run_context_tools: ['scout-emit-report', 'scout-notes-list', 'skill-get', 'skill-file-get'],grantable_write_scopes: ['dashboard:write', 'insight:write'],}diff --git a/products/signals/frontend/inbox/components/config/scouts/scoutTools.test.ts b/products/signals/frontend/inbox/components/config/scouts/scoutTools.test.tsindex 25349a2b3676..b854d19a10ec 100644--- a/products/signals/frontend/inbox/components/config/scouts/scoutTools.test.ts+++ b/products/signals/frontend/inbox/components/config/scouts/scoutTools.test.ts@@ -19,6 +19,7 @@ describe('scoutTools', () => {['DASHBOARD', ['Dashboards']],// The run context tools are always held, so a search never offers them as choices.['scout', []],+ ['skill', []],])('groups the selectable tools for search %p', (search, categories) => {expect(groupScoutTools(SCOUT_TOOL_CATALOGUE, search).map((group) => group.category)).toEqual(categories)})diff --git a/products/signals/frontend/inbox/components/config/scouts/scoutTools.ts b/products/signals/frontend/inbox/components/config/scouts/scoutTools.tsindex 9188573fd928..e6046395f457 100644--- a/products/signals/frontend/inbox/components/config/scouts/scoutTools.ts+++ b/products/signals/frontend/inbox/components/config/scouts/scoutTools.ts@@ -1,24 +1,5 @@import type { ScoutToolCatalogueApi, ScoutToolCatalogueEntryApi } from 'products/signals/frontend/generated/api.schemas'-/**- * The tools every scout run holds whatever its list says, mirroring `SCOUT_RUN_CONTEXT_TOOLS` in- * `products/signals/backend/scout_harness/tool_catalogue.py`. The API rejects a list that names one,- * so the picker shows them apart and never sends them.- */-export const SCOUT_RUN_CONTEXT_TOOLS: readonly string[] = [- 'scout-emit-report',- 'scout-edit-report',- 'scout-emit-signal',- 'scout-scratchpad-search',- 'scout-scratchpad-remember',- 'scout-scratchpad-forget',- 'scout-notes-list',- 'scout-metadata-get',- 'scout-project-profile-get',- 'scout-record-output',- 'scout-check-record-result',-]-export interface ScoutToolGroup {category: stringtools: ScoutToolCatalogueEntryApi[]@@ -31,12 +12,12 @@ export function scoutToolUnavailableReason(tool: ScoutToolCatalogueEntryApi): st/** The catalogue tools a list can name: everything except the run context tools. */export function selectableScoutTools(catalogue: ScoutToolCatalogueApi): ScoutToolCatalogueEntryApi[] {- return catalogue.tools.filter((tool) => !SCOUT_RUN_CONTEXT_TOOLS.includes(tool.name))+ return catalogue.tools.filter((tool) => !catalogue.run_context_tools.includes(tool.name))}/** Labels for the run context tools, for the always-held group. A tool the catalogue lacks shows its name. */export function runContextScoutToolLabels(catalogue: ScoutToolCatalogueApi): string[] {- return SCOUT_RUN_CONTEXT_TOOLS.map((name) => catalogue.tools.find((tool) => tool.name === name)?.title || name)+ return catalogue.run_context_tools.map((name) => catalogue.tools.find((tool) => tool.name === name)?.title || name)}/**diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex e688b29e978d..f0264b437af9 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -102444,6 +102444,8 @@ export namespace Schemas {tools: ScoutToolCatalogueEntry[];/** Tool selections expanded and validated on save. */tool_presets: ScoutToolPreset[];+ /** Tools every scout run holds. Show these as always available, excluding them from saved selections. */+ readonly run_context_tools: readonly string[];/** The scope presets a scout run can be dispatched with, and the scopes each one resolves to. */presets: ScoutScopePreset[];/** The write scopes a person can grant to one scout from its settings. A scope outside this set can never be added to a scout's token. */diff --git a/services/mcp/src/hono/analytics.ts b/services/mcp/src/hono/analytics.tsindex edcb0ecdb39f..7a01efc1a1a5 100644--- a/services/mcp/src/hono/analytics.ts+++ b/services/mcp/src/hono/analytics.ts@@ -77,6 +77,8 @@ function buildBaseProperties(// Which kind of caller minted this token — scout, research run, implementation run, or// ordinary user — so scratchpad and notes calls split by caller in one breakdown.$mcp_scope_preset: resolveScopePreset(state.apiKeyScopes),+ // Server-derived from introspection, so a refused call can be traced to the run it came from.+ ...(state.sandboxTaskId ? { sandbox_task_id: state.sandboxTaskId } : {}),...(analyticsContext? {$mcp_organization_id: analyticsContext.organizationId,diff --git a/services/mcp/src/hono/request-state-resolver.ts b/services/mcp/src/hono/request-state-resolver.tsindex bd34399664c2..866a977e5fe1 100644--- a/services/mcp/src/hono/request-state-resolver.ts+++ b/services/mcp/src/hono/request-state-resolver.ts@@ -71,6 +71,14 @@ export interface ResolvedState {allTools: Tool<ZodObjectAny>[]scopeGatedTools: ScopeGatedTool[]flagGatedTools: FlagGatedTool[]+ /**+ * The tools a scout run with a picked tool list holds, from token introspection.+ * Undefined means no per-tool policy. Every other tool is hidden, and exec refuses it+ * as `tool_not_granted`.+ */+ heldTools?: ReadonlySet<string> | undefined+ /** The task a sandbox token is bound to, from token introspection. */+ sandboxTaskId?: string | undefined/*** Whether the caller's team may reach third-party MCP tools through `exec`.* Gated on the same flag as the gateway UI — the tools are the gateway's payoff,@@ -300,18 +308,25 @@ export class RequestStateResolver {availableFeatures,isCloud,}+ // The held set is a server-derived ceiling on top of every other filter, so a tool+ // outside it is neither listed nor offered as a gated hint the agent could chase.+ const heldTools = _apiKey?.mcp_allowed_tools ? new Set(_apiKey.mcp_allowed_tools) : undefined+ const isHeld = (tool: { name: string }): boolean => !heldTools || heldTools.has(tool.name)+// Staff-only tools (OAuth-hidden scopes) need the extra explicit-scope +// is_staff gate on top of the catalog's plain scope filter.- const allTools = await filterStaffOnlyTools(- this.catalog.getFilteredTools({ ...filterOptions, scopes: apiKeyScopes }),- _apiKey ?? { scopes: [] },- () => context.stateManager.getUser()- )+ const allTools = (+ await filterStaffOnlyTools(+ this.catalog.getFilteredTools({ ...filterOptions, scopes: apiKeyScopes }),+ _apiKey ?? { scopes: [] },+ () => context.stateManager.getUser()+ )+ ).filter(isHeld)// Scope-gated hints are only consumed by the exec `search` command, which// only exists in single-exec mode — skip the extra scan otherwise.- const scopeGatedTools = useSingleExec ? getScopeGatedTools(apiKeyScopes, filterOptions) : []+ const scopeGatedTools = useSingleExec ? getScopeGatedTools(apiKeyScopes, filterOptions).filter(isHeld) : []// Only exec redirects a call to a gated tool; tools mode just omits it.- const flagGatedTools = useSingleExec ? getFlagGatedTools(filterOptions) : []+ const flagGatedTools = useSingleExec ? getFlagGatedTools(filterOptions).filter(isHeld) : []return {reqCtx,@@ -334,6 +349,8 @@ export class RequestStateResolver {scopeGatedTools,flagGatedTools,gatewayToolFilter: { tools, features, excludeTools },+ heldTools,+ sandboxTaskId: _apiKey?.sandbox_task_id,gatewayToolsEnabled:useSingleExec &&!readOnly &&diff --git a/services/mcp/src/hono/tool-executor.ts b/services/mcp/src/hono/tool-executor.tsindex f79e6b5c2c07..05580274e098 100644--- a/services/mcp/src/hono/tool-executor.ts+++ b/services/mcp/src/hono/tool-executor.ts@@ -60,7 +60,7 @@ import { EXECUTE_SQL_TOOL_NAME } from '@/tools/posthogAiTools/executeSql'import { createRenderUiTool } from '@/tools/render-ui'import { skillAnalyticsProperties, skillLookupMissProperties } from '@/tools/skills/analytics'import { type BuiltInSkillHint, formatSkillLookupMiss, type SkillLookupMissKind } from '@/tools/skills/notFound'-import { getToolIngestedData } from '@/tools/toolDefinitions'+import { getToolDefinitions, getToolIngestedData } from '@/tools/toolDefinitions'import type { Context, Tool, ZodObjectAny } from '@/tools/types'import {@@ -953,6 +953,7 @@ export class ToolExecutor {this.skillCatalogService?.getCatalog()),flagGatedTools: state.flagGatedTools,+ ...(state.heldTools ? { heldTools: state.heldTools } : {}),builtInSkillHint: this.builtInSkillHint(state),...(state.gatewayToolsEnabled? {@@ -1102,11 +1103,12 @@ function resolveToolErrorClassification(error: unknown): ToolErrorClassification}}// Agent-recoverable command mistakes, so keep them out of the `internal` rate- // ops alerts on. `missing_scope` is the exception: no input the agent sends- // fixes it, the connection has to be reauthorized.+ // ops alerts on. `missing_scope` and `tool_not_granted` are the exceptions: no+ // input the agent sends fixes them, the grant has to change.if (error instanceof ExecCommandError) {return {- errorType: error.reason === 'missing_scope' ? 'permission' : 'validation',+ errorType:+ error.reason === 'missing_scope' || error.reason === 'tool_not_granted' ? 'permission' : 'validation',errorCode: error.reason,}}@@ -1319,7 +1321,7 @@ function errorAnalyticsProperties(classification: ToolErrorClassification, error* schema discovery, tool search, and a mistyped verb are indistinguishable, and* an `unknown_tool` rejection records nothing about what was attempted. Both* values are value-free by construction (see `describeExecCommand`): the verb comes- * from the closed grammar and the target from this connection's own catalog, so a+ * from the closed grammar and the target from the server's tool catalog, so a* token outside either is recorded as unrecognized rather than echoed.*/function execCommandAnalyticsProperties(execArgs: unknown, state: ResolvedState): Record<string, unknown> {@@ -1332,7 +1334,8 @@ function execCommandAnalyticsProperties(execArgs: unknown, state: ResolvedState)(name) =>state.allTools.some((t) => t.name === name) ||state.scopeGatedTools.some((t) => t.name === name) ||- state.flagGatedTools.some((t) => t.name === name)+ state.flagGatedTools.some((t) => t.name === name) ||+ Object.prototype.hasOwnProperty.call(getToolDefinitions(), name))return {...(verb !== undefined ? { $mcp_exec_verb: verb } : {}),diff --git a/services/mcp/src/lib/StateManager.ts b/services/mcp/src/lib/StateManager.tsindex fa7b966d5af8..22faf4a759af 100644--- a/services/mcp/src/lib/StateManager.ts+++ b/services/mcp/src/lib/StateManager.ts@@ -163,6 +163,12 @@ export class StateManager {is_impersonated: introspectionResult.data.is_impersonated === true,// Only server-minted sandbox tokens can carry this scope; request headers cannot opt out.suppress_analytics: (scope ?? '').split(' ').includes('scout_experiment_internal:read'),+ ...(introspectionResult.data.sandbox_task_id+ ? { sandbox_task_id: introspectionResult.data.sandbox_task_id }+ : {}),+ ...(introspectionResult.data.mcp_allowed_tools+ ? { mcp_allowed_tools: introspectionResult.data.mcp_allowed_tools }+ : {}),}}diff --git a/services/mcp/src/lib/errors.ts b/services/mcp/src/lib/errors.tsindex 0792d3876264..7d48e6825763 100644--- a/services/mcp/src/lib/errors.ts+++ b/services/mcp/src/lib/errors.ts@@ -205,6 +205,7 @@ export type ExecCommandErrorReason =| 'deprecated_tool'| 'gated_tool'| 'missing_scope'+ | 'tool_not_granted'| 'invalid_json'| 'usage'| 'invalid_regex'diff --git a/services/mcp/src/schema/api.ts b/services/mcp/src/schema/api.tsindex 5f370f0718d1..b292c9bc520e 100644--- a/services/mcp/src/schema/api.ts+++ b/services/mcp/src/schema/api.ts@@ -47,6 +47,10 @@ export interface ApiRedactedPersonalApiKey {scopes: string[]scoped_teams: number[]scoped_organizations: string[]+ // Set only for a token minted for a sandboxed task run. Read from introspection, never a header.+ sandbox_task_id?: string+ // The tools a run with a picked tool list holds. Absent means no per-tool policy.+ mcp_allowed_tools?: string[]}export type ApiOAuthIntrospection =@@ -58,6 +62,8 @@ export type ApiOAuthIntrospection =scoped_organizations: string[]client_name?: stringclient_id?: string+ sandbox_task_id?: string+ mcp_allowed_tools?: string[]}| {active: falsediff --git a/services/mcp/src/tools/exec.ts b/services/mcp/src/tools/exec.tsindex 9172ada683bf..f92a9117a7a9 100644--- a/services/mcp/src/tools/exec.ts+++ b/services/mcp/src/tools/exec.ts@@ -256,6 +256,11 @@ export interface ExecToolOptions {* is the case where an agent has no way to reach a built-in skill at all.*/builtInSkillHint?: BuiltInSkillHint+ /**+ * The tools a scout run with a picked tool list holds. A catalog tool outside this set is+ * refused as `tool_not_granted`, so the agent does not search for another way to reach it.+ */+ heldTools?: ReadonlySet<string>}const CALL_USAGE = 'Usage: call [--json] [--confirm] <tool_name> [json_input]'@@ -1670,7 +1675,8 @@ function findTool(scopeGatedTools: ScopeGatedTool[],flagGatedTools: FlagGatedTool[],name: string,- context: Context | undefined+ context: Context | undefined,+ heldTools: ReadonlySet<string> | undefined): Tool<ZodObjectAny> {const tool = tools.find((t) => t.name === name)if (!tool) {@@ -1689,6 +1695,12 @@ function findTool('missing_scope')}+ if (heldTools && !heldTools.has(name) && getToolDefinitions()[name] !== undefined) {+ throw new ExecCommandError(+ `Tool "${name}" exists, but the owner of this run did not grant it. This refusal is final. Do not retry it, and do not reach the same data or action another way.`,+ 'tool_not_granted'+ )+ }throw new ExecCommandError(`Unknown tool: "${name}". Run "search ${name}" to find the current tool name before claiming the capability is unavailable.`,'unknown_tool'@@ -1888,7 +1900,14 @@ export function createExecTool(if (!infoArgs) {throw new ExecCommandError('Usage: info [--json] <tool_name>', 'usage')}- const tool = findTool(await resolveTools(), scopeGatedTools, flagGatedTools, infoArgs, context)+ const tool = findTool(+ await resolveTools(),+ scopeGatedTools,+ flagGatedTools,+ infoArgs,+ context,+ options.heldTools+ )// `io: 'input'` mirrors the advertised `tools/list` schema and the executor's// validation: fields with a Zod `.default()` (e.g. a query `kind` discriminator)// are optional and auto-filled. The default `io: 'output'` would list them as@@ -1938,7 +1957,8 @@ export function createExecTool(scopeGatedTools,flagGatedTools,schemaToolName,- context+ context,+ options.heldTools)// See the `info` command: `io: 'input'` keeps this in sync with the advertised// schema and validation, so `.default()` fields aren't shown as required.@@ -1996,7 +2016,14 @@ export function createExecTool(throw new ExecCommandError(CALL_USAGE, 'usage')}const { verb: toolName, rest: jsonBody } = parseCommand(callArgs)- const tool = findTool(await resolveTools(), scopeGatedTools, flagGatedTools, toolName, context)+ const tool = findTool(+ await resolveTools(),+ scopeGatedTools,+ flagGatedTools,+ toolName,+ context,+ options.heldTools+ )if (options.requireDestructiveConfirmation && tool.annotations.destructiveHint && !confirmed) {throw new ExecCommandError(`Tool "${tool.name}" is destructive. Re-run with "call --confirm ${tool.name} ..." after verifying the target IDs. Use "info ${tool.name}" to inspect the tool first.`,diff --git a/services/mcp/tests/hono/request-state-resolver.test.ts b/services/mcp/tests/hono/request-state-resolver.test.tsindex 8bba50c4e270..e9334dd4b911 100644--- a/services/mcp/tests/hono/request-state-resolver.test.ts+++ b/services/mcp/tests/hono/request-state-resolver.test.ts@@ -20,6 +20,7 @@ const {scoped_teams: [],is_impersonated: undefined as boolean | undefined,suppress_analytics: undefined as boolean | undefined,+ mcp_allowed_tools: undefined as string[] | undefined,},mockSessionScopedStores: new Map<string, Map<string, unknown>>(),// Records the keys passed to every session-scoped refreshTtl call (only the@@ -204,6 +205,7 @@ describe('RequestStateResolver MCP client contexts', () => {mockApiKey.scopes = ['*']mockApiKey.is_impersonated = undefinedmockApiKey.suppress_analytics = undefined+ mockApiKey.mcp_allowed_tools = undefined})it.each([true, false, undefined])(@@ -879,6 +881,21 @@ describe('RequestStateResolver MCP client contexts', () => {)})+ // A gated hint outside the held set would send the agent after a tool it can never get.+ it('limits the roster and the gated hints to the held tool set', async () => {+ mockApiKey.scopes = ['project:read']+ mockApiKey.mcp_allowed_tools = ['docs-search', 'dashboards-get-all']+ const catalog = new ToolCatalog()+ await catalog.warmup()+ const resolver = new RequestStateResolver(catalog, {} as RedisLike, {} as Env)++ const result = await resolver.resolve(makeProps({ mode: 'cli' }))++ expect(result.allTools.map((tool) => tool.name)).toEqual(['docs-search'])+ expect(result.scopeGatedTools.map((tool) => tool.name)).toEqual(['dashboards-get-all'])+ expect(result.flagGatedTools).toEqual([])+ })+it('merges request excludeTools into catalog filter options', async () => {const { resolver, getFilteredTools } = makeResolverWithCatalog()diff --git a/services/mcp/tests/hono/tool-executor-metrics.test.ts b/services/mcp/tests/hono/tool-executor-metrics.test.tsindex 9dcbd22bba57..350e18f22907 100644--- a/services/mcp/tests/hono/tool-executor-metrics.test.ts+++ b/services/mcp/tests/hono/tool-executor-metrics.test.ts@@ -806,22 +806,23 @@ describe('ToolExecutor metrics', () => {expect(mockTrackToolCall.mock.calls.at(-1)?.[4]).not.toHaveProperty('$mcp_input_keys')})- // A name a feature flag retired is one we own, so it is recordable like any- // other. Recorded as unrecognized instead, the `gated_tool` class counts the- // wasted round trips without naming the rename that caused them.- it('stamps the retired tool a flag gate removed, not the unrecognized sentinel', async () => {+ it.each(['gated_tool', 'tool_not_granted'] as const)('stamps the target tool on %s', async (reason) => {const state = execState()- // What the resolver produces with the gate on: the flag filter drops the- // tool from the catalog, and `getFlagGatedTools` picks it up.state.allTools = state.allTools.filter((tool) => tool.name !== 'notebooks-create')- state.flagGatedTools = [{ name: 'notebooks-create', supersededBy: ['notebooks-create-markdown'] }]+ if (reason === 'gated_tool') {+ state.flagGatedTools = [{ name: 'notebooks-create', supersededBy: ['notebooks-create-markdown'] }]+ } else {+ state.scopeGatedTools = []+ state.flagGatedTools = []+ state.heldTools = new Set(['docs-search'])+ }await executor.handleToolCall({ name: 'exec', arguments: { command: 'call notebooks-create {}' } }, state)expect(mockTrackToolCall.mock.calls.at(-1)?.[4]).toMatchObject({$mcp_exec_verb: 'call',$mcp_exec_target_tool: 'notebooks-create',- $mcp_error_code: 'gated_tool',+ $mcp_error_code: reason,})})diff --git a/services/mcp/tests/unit/exec.test.ts b/services/mcp/tests/unit/exec.test.tsindex 90f6046dd6d8..bb5101ebfa78 100644--- a/services/mcp/tests/unit/exec.test.ts+++ b/services/mcp/tests/unit/exec.test.ts@@ -1878,6 +1878,27 @@ describe('exec tool', () => {})})+ describe('held tool set', () => {+ const heldTools = new Set(['notebooks-create-markdown'])+ const exec = createExec([makeMockTool({ name: 'notebooks-create-markdown' })], undefined, { heldTools })++ // An unknown-tool reply sends the agent to `search` for another way to reach the operation.+ it.each(['info notebooks-create', 'schema notebooks-create', 'call notebooks-create {}'])(+ 'refuses a catalog tool outside the held set as not granted on %s',+ async (command) => {+ await expect(exec.handler(mockContext, { command })).rejects.toMatchObject({+ reason: 'tool_not_granted',+ })+ }+ )++ it('still reports a name the catalog does not have as unknown', async () => {+ await expect(exec.handler(mockContext, { command: 'call not-a-posthog-tool {}' })).rejects.toMatchObject({+ reason: 'unknown_tool',+ })+ })+ })+describe('flag-gated tool redirects', () => {const notebooksCreateMarkdown = makeMockTool({ name: 'notebooks-create-markdown' })