Introduction to StackOne AI SDK
Relevant source files
The following files were used as context for generating this wiki page:
StackOne AI SDK provides a unified Python interface for accessing SaaS tools through AI-friendly APIs. It supports integrations with OpenAI, LangChain, LangGraph, Pydantic AI, and the Model Context Protocol (MCP). The SDK fetches tool schemas at runtime from an MCP server, ensuring that the model receives the exact schema the server serves without loss of detail or invention.
Sources: README.md:1-5, CLAUDE.md:8-12, CLAUDE.md:17-19
The SDK requires Python 3.11 or higher. It uses uv for dependency management and organizes its functionality into three primary modules: types.py for shared data structures, tools.py for tool execution logic, and toolset.py for account discovery and catalog management.
Sources: README.md:16-18, CLAUDE.md:14-25, pyproject.toml:6-7
Core Features and Architecture
The SDK handles complex SaaS integrations by offloading tool discovery and schema management to the StackOne API. This approach prevents large tool catalogs from overwhelming a model's context window.
Sources: README.md:9-14
System Features
| Feature | Description |
|---|---|
| Search and Execute | Finds actions using natural language and executes them without fitting the full catalog in context. |
| Account Discovery | Automatically finds linked accounts using only an API key. |
| MCP-Backed | Fetches tools at runtime; model sees the exact schema served by the StackOne server. |
| Framework Adapters | Native support for OpenAI, LangChain, LangGraph, and Pydantic AI. |
| Dynamic Filtering | Filters tools by account, provider, and glob action patterns. |
Sources: README.md:9-14, CLAUDE.md:27-29
Architecture Overview
The following diagram represents the relationship between the user application, the StackOne SDK, and the remote API infrastructure.
The diagram shows the three primary interaction points between the SDK and the StackOne API: account discovery, catalog fetching via MCP, and action execution via RPC.
Sources: CLAUDE.md:21-29, stackone_ai/tools.py:108-112, stackone_ai/tools.py:734-738
Calling Surfaces
The SDK provides two distinct surfaces for interacting with SaaS actions. Each surface requires different argument shapes to match its specific execution endpoint.
Sources: CLAUDE.md:31-33
1. Meta-Tool Surface (search and execute)
Users discover actions at runtime using natural language. The SDK calls per-connector meta-tools (_search_actions and _execute_action) via the MCP endpoint.
- Argument Shape: Nested envelope, e.g.,
{"body": {"variables": {...}}}. - Use Case: Best for agents that need to browse a massive catalog of hundreds of tools.
Sources: CLAUDE.md:35-37, README.md:121-125
2. Per-Action Tool Surface (fetch_tools)
Users bind a fixed, filtered set of tools to a model. The SDK interacts with individual action schemas over the RPC endpoint.
- Argument Shape: Flat-prefixed keys, e.g.,
body_variables,path_id. - Use Case: Best for binding specific tools to framework-native tool calling (OpenAI, LangChain).
Sources: CLAUDE.md:38-39, README.md:121-125
Authentication and Account Scoping
Authentication requires a STACKONE_API_KEY. The SDK scopes requests to specific accounts using the x-account-id header.
Sources: README.md:26-30, examples/auth_management.py:25-30
from stackone_ai import StackOneToolSet
# Reads STACKONE_API_KEY from environment
toolset = StackOneToolSet()
# Scope tools to a specific account
tools = toolset.fetch_tools(account_ids=["acc-123"])
Sources: README.md:26-34, examples/auth_management.py:53-58
Data Models and Types
The SDK uses Pydantic for data validation and schema management. Key types include ToolParameters, which holds the JSON Schema of a tool, and ExecuteConfig, which defines the HTTP request requirements.
Sources: stackone_ai/types.py:126-140, stackone_ai/types.py:175-185
Parameter Locations
Parameters are mapped to specific locations in the outgoing API request:
| Location | Description |
|---|---|
HEADER | Passed in HTTP headers. |
QUERY | Passed as URL query parameters. |
PATH | Substituted into the URL path template. |
BODY | Sent in the JSON or form request body. |
FILE | Used for binary file uploads. |
Sources: stackone_ai/types.py:84-91
Execution Flow
When a tool is executed, the SDK prepares the authentication headers and splits parameters into the correct RPC envelope.
Sources: stackone_ai/tools.py:500-515, stackone_ai/tools.py:768-780
This sequence illustrates how arguments are processed through the internal _split_envelope_params logic before being sent to the RPC endpoint.
Sources: stackone_ai/tools.py:588-605, stackone_ai/tools.py:768-782, stackone_ai/tools.py:785-840
Error Handling
All SDK exceptions derive from a common hierarchy, allowing users to catch all errors using StackOneError.
Sources: stackone_ai/types.py:44-55, CLAUDE.md:133-135
StackOneAPIError: Raised when the remote API returns an error status (e.g., 400, 401, 429). Includes the status code and raw response body.ToolsetConfigError: Raised for configuration issues like missing API keys.ToolsetLoadError: Raised when the MCP catalog fails to load.
Sources: stackone_ai/types.py:51-78
Summary
The StackOne AI SDK enables Python applications to interact with hundreds of SaaS connectors using a standardized interface. By leveraging the Model Context Protocol (MCP), it ensures that AI models receive precise, runtime-fetched tool schemas while maintaining a lightweight context footprint through semantic search and execute patterns.
Sources: README.md:9-14, CLAUDE.md:17-25