Quick Start & Installation
Relevant source files
The following files were used as context for generating this wiki page:
The StackOne AI SDK provides a unified Python interface for accessing SaaS tools through AI-friendly APIs. It supports integrations with OpenAI, LangChain, LangGraph, and Pydantic AI, using the Model Context Protocol (MCP) to fetch tool schemas at runtime.
Sources: README.md:1-5, CLAUDE.md:7-10
Requirements & Prerequisites
The SDK requires Python 3.11 or higher. It depends on several core libraries to facilitate communication with the StackOne API and manage tool schemas.
Sources: pyproject.toml:6, CLAUDE.md:12
Core Dependencies
| Library | Version | Purpose |
|---|---|---|
pydantic | >= 2.10.6 | Data validation and settings management. |
httpx | >= 0.28.0 | Asynchronous and synchronous HTTP client. |
mcp | >= 1.24.3 | Model Context Protocol client for tool discovery. |
Sources: pyproject.toml:20-27
Installation
Install the core SDK using uv or pip. The package uses optional "extras" for specific framework adapters to avoid unnecessary dependencies.
Basic Installation
uv add stackone-ai
Sources: README.md:36
Installing Framework Adapters
If you use specific AI frameworks, install the corresponding extras:
- LangChain / LangGraph:
uv add 'stackone-ai[langchain]' - Pydantic AI:
uv add 'stackone-ai[pydantic-ai]' - Examples & Development:
uv add 'stackone-ai[examples,dev]'
Sources: README.md:39-41, pyproject.toml:37-45
Authentication and Configuration
The SDK requires a STACKONE_API_KEY to authenticate requests. You can provide this key through environment variables or explicit constructor parameters.
Providing the API Key
- Environment Variable: Set
STACKONE_API_KEYin your shell or a.envfile. TheStackOneToolSetclass reads this by default. - Explicit Parameter: Pass the
api_keyargument when initializing theStackOneToolSet.
Sources: README.md:46-48, examples/auth_management.py:35-43
Account Discovery
The SDK automatically discovers linked accounts if you do not specify an account_id. It calls the /accounts endpoint and uses all accounts marked as active.
The diagram shows the initialization flow and how the SDK handles account discovery when credentials are not explicitly scoped.
Sources: CLAUDE.md:28-30, stackone_ai/types.py:64-67
Core Workflow
The SDK offers two primary surfaces for interacting with SaaS tools: Meta-tool Search and Explicit Fetching.
Comparison of Calling Surfaces
| Feature | search() + execute() | fetch_tools() + tool.execute() |
|---|---|---|
| Discovery | Runtime natural language search. | Pre-defined filtering (glob patterns). |
| Argument Shape | Nested envelope: {"body": {"variables": {...}}}. | Flat-prefixed: body_variables, path_id. |
| Context Window | High efficiency; only top-K hits sent. | Potentially large; filters tool catalog. |
| Implementation | StackOneMcpTool via tools/call. | StackOneRpcTool via /actions/rpc. |
Sources: CLAUDE.md:36-47, README.md:220-228
Basic Usage Example
from stackone_ai import StackOneToolSet
# 1. Initialize
toolset = StackOneToolSet()
# 2. Search for an action
hits = toolset.search("list recent comments", top_k=3)
# 3. Execute the action using action_id and nested arguments
result = toolset.execute(
"linear_list_comments",
{"body": {"variables": {"first": 25}}}
)
Sources: README.md:52-65
Data Flow Architecture
The SDK acts as a bridge between AI models and the StackOne API, translating tool schemas and executing requests.
The sequence diagram illustrates how a model-driven tool search results in a specific RPC execution against a SaaS provider.
Sources: CLAUDE.md:15-22, stackone_ai/tools.py:12-18
Summary
The Quick Start process involves installing the stackone-ai package, configuring the STACKONE_API_KEY, and utilizing the StackOneToolSet to discover and execute actions. Users should choose between the search() workflow for dynamic discovery or fetch_tools() for binding a static set of tools to a model context.
Sources: README.md:46-70, CLAUDE.md:105-115