---
title: "Set agent session-start hook"
method: PUT
path: "/v1/agents/{id}/session-start-hook"
---

# Set agent session-start hook

`PUT /v1/agents/{id}/session-start-hook`

## Request

- Base URL: `https://api.runbear.io`
- URL: `https://api.runbear.io/v1/agents/{id}/session-start-hook`
- Auth: HTTP bearer

Set or replace the agent's session-start hook on the Custom MCP integration named by `app`. The hook tool is invoked server-side at session start and hidden from the model. Returns 404 when the agent is not found / unsupported, or when the agent has no Custom MCP integration with the given `app`.

## Path parameters

- `id` string, uuid, required: Agent ID

## Request body

- SessionStartHookSetRequest
  - `app` string, required: Custom MCP integration namespace (`app`) that hosts the hook tool.
  - `toolName` string, required: Name of the MCP tool invoked server-side once at session start. Hidden from the model's tool list.
  - `timeoutMs` integer: Per-call timeout in milliseconds. On timeout the engine degrades gracefully (responds without injected context). Omit for the engine default.
  - `staticArgs` object: Constant arguments always passed to the hook tool, applied only when the tool's input schema declares a matching property (e.g. an authorization key: `{ "invocation_key": "…" }`). NON-SECRET values only — secrets belong in the integration's `httpHeaders`.

## Response `200`

Default Response

- SessionStartHookOutput
  - `app` string, required: Custom MCP integration namespace (`app`) that hosts the hook tool.
  - `toolName` string, required: Name of the MCP tool invoked server-side once at session start. Hidden from the model's tool list.
  - `timeoutMs` integer: Per-call timeout in milliseconds. On timeout the engine degrades gracefully (responds without injected context). Omit for the engine default.
  - `staticArgs` object: Constant arguments always passed to the hook tool, applied only when the tool's input schema declares a matching property (e.g. an authorization key: `{ "invocation_key": "…" }`). NON-SECRET values only — secrets belong in the integration's `httpHeaders`.

## Other responses

- `404`: Default Response

---

[API](https://skmtc.dev/runbear/apis/runbear-api.md) - [All operations](https://skmtc.dev/runbear/apis/runbear-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runbear/apis/runbear-api/revisions/c6a9c3066a5a?raw)