StackOneMcpTool Meta Tools
Relevant source files
The following files were used as context for generating this wiki page:
StackOne Meta Tools provide a discovery and execution layer that manages large catalogs of SaaS actions through a minimized set of tools. When you enable the search_execute mode, the SDK serves two specific meta tools per connector instead of listing every individual action as a unique tool. This mechanism keeps the tool catalog within the context window limits of Large Language Models (LLMs) regardless of the number of linked accounts.
Sources: stackone_ai/types.py:19-27, stackone_ai/toolset.py:59-62, CLAUDE.md:16-19
Tool Mode: search_execute
The search_execute mode changes how the MCP endpoint lists tools. Instead of hundreds of per-action tools, the server provides two meta tools for each linked connector. The StackOneToolSet class manages this behavior through the tool_mode parameter.
Sources: stackone_ai/types.py:19-27, stackone_ai/toolset.py:277-283
Comparison of Tool Modes
| Feature | individual (Default) | search_execute (Meta) |
|---|---|---|
| Catalog Size | One tool per action (Large) | Two tools per connector (Small) |
| Discovery | Model chooses from full list | Model calls search_actions first |
| Execution Path | /actions/rpc (usually) | MCP tools/call |
| Argument Shape | Flat-prefixed | Nested envelope |
Sources: stackone_ai/types.py:19-27, CLAUDE.md:30-40, stackone_ai/toolset.py:355-365
Architecture and Class Hierarchy
Meta tools are implemented via the StackOneMcpTool class, which inherits from StackOneTool. Unlike StackOneRpcTool which targets the RPC endpoint, StackOneMcpTool executes calls back through the Model Context Protocol (MCP) transport.
The diagram shows the inheritance structure where StackOneMcpTool provides the specialized execution logic for MCP-based meta tools.
Sources: stackone_ai/tools.py:284-290, stackone_ai/tools.py:530-540, stackone_ai/tools.py:590-595
Functional Meta Tools
Every connector in search_execute mode provides two standardized tools. The SDK identifies these tools by their suffixes.
1. Action Search (*_search_actions)
This tool allows the model to search for available actions using natural language. It returns a list of action IDs, descriptions, and example requests. The StackOneToolSet.search() method internally calls this tool across all connectors.
Sources: stackone_ai/toolset.py:285-300, tests/mocks/mcp-server.ts:98-105
2. Action Execution (*_execute_action)
This tool executes a specific action identified by an action_id. It accepts a nested argument envelope. The StackOneToolSet.execute() method routes calls to this tool by matching the action ID prefix to the appropriate connector.
Sources: stackone_ai/toolset.py:355-375, tests/mocks/mcp-server.ts:121-131
Data Flow: Search and Execute
The following sequence diagram illustrates how StackOneToolSet coordinates with StackOneMcpTool to perform a natural language search.
The sequence demonstrates the fan-out search across connectors and the global ranking performed by the SDK.
Sources: stackone_ai/toolset.py:285-334, stackone_ai/tools.py:612-618
Execution Envelope and Security
Meta tools require a nested argument envelope. This structure separates parameters into path, query, body, and headers blocks.
Argument Structure
{
"action_id": "linear_list_comments",
"body": {
"variables": {
"first": 25
}
}
}
Sources: CLAUDE.md:30-34, stackone_ai/toolset.py:382-386
Header Sanitization
StackOneMcpTool performs security checks on model-supplied headers. It drops any header that the served schema did not declare to prevent prompt injection attacks that might attempt to override authentication or account context.
Sources: stackone_ai/tools.py:417-430, stackone_ai/tools.py:609-616
Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
query | str | The natural language search string. |
top_k | int | Maximum results per connector (1-50). |
action_id | str | The unique identifier for the SaaS action. |
arguments | dict | The nested parameters for the target action. |
Sources: stackone_ai/toolset.py:293-294, stackone_ai/toolset.py:302-305, stackone_ai/toolset.py:356-357
Summary
StackOneMcpTool Meta Tools optimize the interaction between LLMs and SaaS platforms by providing a scalable discovery mechanism. By using search_actions and execute_action, the SDK enables agents to navigate hundreds of available integrations without exceeding token limits or sacrificing the precision of the underlying SaaS APIs.
Sources: stackone_ai/toolset.py:285-290, stackone_ai/types.py:19-27