Skip to content

: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.

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.md
index 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 i
While 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 del
A 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 attribution
diff --git a/posthog/api/oauth/views.py b/posthog/api/oauth/views.py
index 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_id
data["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 has
diff --git a/products/signals/backend/facade/tool_policy.py b/products/signals/backend/facade/tool_policy.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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):
continue
diff --git a/products/signals/backend/test/test_scout_harness_api.py b/products/signals/backend/test/test_scout_harness_api.py
index 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.py
index 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.ts
index 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.tsx
index 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 }: Sco
const { 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 }: Sco
body = (
<ToolCatalogueBody
catalogue={catalogue}
- selected={selected}
+ selected={selectedTools}
preset={preset}
onChange={(tools, nextPreset = null) => {
setSelected(tools)
@@ -91,7 +92,7 @@ export function ScoutToolsPicker({ scoutName, savedTools, onSave, onClose }: Sco
type="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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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: string
tools: 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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?: string
client_id?: string
+ sandbox_task_id?: string
+ mcp_allowed_tools?: string[]
}
| {
active: false
diff --git a/services/mcp/src/tools/exec.ts b/services/mcp/src/tools/exec.ts
index 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.ts
index 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 = undefined
mockApiKey.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.ts
index 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.ts
index 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' })