Tool Modes

Overview

The StackOne MCP endpoint supports two tool registration modes controlled by the tool-mode query parameter:

Mode	Tools registered	Best for
`individual` (default)	One tool per action	Agents with a small action set, or full tool visibility
`search_execute`	2 tools: search + execute	Large catalogs, context window constraints

Individual Mode (Default)

When tool-mode is omitted or set to individual, StackOne registers each enabled action as its own MCP tool (e.g., bamboohr_list_employees, ashby_list_jobs). This is the right choice when:

Your integration config has a small, focused action set
You want the LLM to see every available tool upfront
Your MCP client supports large tool lists without performance degradation

Search & Execute Mode

https://api.stackone.com/mcp?tool-mode=search_execute&x-account-id=<ACCOUNT_ID>

Instead of registering one tool per action, search_execute mode exposes exactly two tools:

Tool	Description
`{provider}_search_actions`	Takes a natural language query and returns ranked matching actions with their `action_id`, description, and similarity score
`{provider}_execute_action`	Executes any action by its `action_id`

For example, for a BambooHR account the tools would be bamboohr_search_actions and bamboohr_execute_action.

Why use this mode?

A typical integration exposes hundreds of actions. Sending every tool definition to the LLM on every request:

Consumes significant context window tokens
Can slow down tool listing in the client
May exceed context limits for models with smaller windows

Search & execute mode keeps the token footprint constant (two tools) regardless of how many actions the integration supports. The agent first calls search_actions with a natural language description of what it wants to do, then calls execute_action with the returned action_id.

How the agent flow works

1. Agent calls {provider}_search_actions(query="list all employees with their departments")
   → Returns: [{ action_id: "list_employees", description: "...", score: 0.94 }, ...]

2. Agent calls {provider}_execute_action(action_id="list_employees", query={ include: "department" })
   → Returns: employee records from the provider

The search tool accepts:

query (required) — natural language description of the task
top_k (optional, default 10, max 50) — number of results to return

The execute tool accepts:

action_id (required) — the action_id returned by the search tool
path (optional) — path parameters (e.g. { "id": "emp_123" } for a get-by-id action)
query (optional) — query parameters (filters, pagination, etc.)
body (optional) — request body for create/update actions
headers (optional) — additional HTTP headers

The agent must call search_actions first to discover valid action_id values before calling execute_action. Do not assume or hardcode action IDs — they are discovered at runtime based on what is enabled for your account.

Example: Enable in Claude Desktop

Add ?tool-mode=search_execute to the MCP URL in your client config:

{
  "mcpServers": {
    "stackone-bamboohr": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://api.stackone.com/mcp?tool-mode=search_execute",
        "--header",
        "Authorization: Basic <BASE64_APIKEY_COLON>",
        "--header",
        "x-account-id: <ACCOUNT_ID>"
      ]
    }
  }
}

Example: Enable in Claude Code

BASE64_KEY=$(echo -n 'YOUR_STACKONE_API_KEY:' | base64 | tr -d '\n')

claude mcp add stackone-bamboohr -- npx -y mcp-remote@latest \
  "https://api.stackone.com/mcp?tool-mode=search_execute" \
  --header "Authorization: Basic $BASE64_KEY" \
  --header "x-account-id: YOUR_ACCOUNT_ID"

Example: Enable via direct HTTP

curl -X POST "https://api.stackone.com/mcp?tool-mode=search_execute" \
  -H "Authorization: Basic <BASE64_APIKEY_COLON>" \
  -H "x-account-id: <ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"tools-1","method":"tools/list"}'

Combining with Param Style

tool-mode can be combined with the param-style query parameter to control how tool input schemas are structured:

`param-style` value	Schema structure
`nested` (default)	Parameters grouped into `path`, `query`, `body`, `headers` objects
`flat_smart`	All parameters at the top level; conflicts resolved automatically
`flat_root`	All parameters at the top level; any conflicting names are prefixed

https://api.stackone.com/mcp?tool-mode=search_execute&param-style=flat_smart

Both parameters are independent — you can use either, both, or neither.

Choosing the Right Mode

Scenario	Recommended mode
Small action set (< 50 tools)	`individual`
Large integration with many actions	`search_execute`
Model with limited context window	`search_execute`
Agent needs to see all tools explicitly	`individual`
Multi-account management via the Management MCP	`individual` (management tools are fixed)

Search & execute mode uses semantic search over your enabled actions. For best results, write queries that describe the business task rather than the technical operation — e.g., “find employees hired this year” rather than “list employees filtered by start date”.

Getting Started

SDKs & Frameworks

Applications & IDEs

API Behavior

Support

Overview

Individual Mode (Default)

Search & Execute Mode

Why use this mode?

How the agent flow works

Example: Enable in Claude Desktop

Example: Enable in Claude Code

Example: Enable via direct HTTP

Combining with Param Style

Choosing the Right Mode

​Overview

​Individual Mode (Default)

​Search & Execute Mode

​Why use this mode?

​How the agent flow works

​Example: Enable in Claude Desktop

​Example: Enable in Claude Code

​Example: Enable via direct HTTP

​Combining with Param Style

​Choosing the Right Mode

Overview

Individual Mode (Default)

Search & Execute Mode

Why use this mode?

How the agent flow works

Example: Enable in Claude Desktop

Example: Enable in Claude Code

Example: Enable via direct HTTP

Combining with Param Style

Choosing the Right Mode