Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stackone.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The StackOne MCP endpoint supports two tool registration modes controlled by the tool-mode query parameter:
ModeTools registeredBest for
individual (default)One tool per actionAgents with a small action set, or full tool visibility
search_execute2 tools: search + executeLarge 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:
ToolDescription
{provider}_search_actionsTakes a natural language query and returns ranked matching actions with their action_id, description, and similarity score
{provider}_execute_actionExecutes 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 valueSchema structure
nested (default)Parameters grouped into path, query, body, headers objects
flat_smartAll parameters at the top level; conflicts resolved automatically
flat_rootAll 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

ScenarioRecommended mode
Small action set (< 50 tools)individual
Large integration with many actionssearch_execute
Model with limited context windowsearch_execute
Agent needs to see all tools explicitlyindividual
Multi-account management via the Management MCPindividual (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”.