Help us improve
Share bugs, ideas, or general feedback.
From stackone-agents
Build AI agents that call StackOne-linked accounts using TypeScript SDK, Python SDK, MCP server, or A2A protocol. Use when user asks to "add StackOne tools to my agent", "set up MCP with StackOne", "list employees from BambooHR in my agent", "integrate StackOne with OpenAI", "build a multi-tenant agent", or "use StackOne with LangChain". Supports OpenAI, Vercel AI SDK, Claude, LangChain, CrewAI, PydanticAI. Do NOT use for account linking setup (use stackone-connect) or platform management (use stackone-platform).
npx claudepluginhub stackonehq/agent-plugins --plugin stackone-agentsHow this skill is triggered — by the user, by Claude, or both
Slash command
/stackone-agents:stackone-agentsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
SDK APIs change frequently. Before writing code:
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Processes PDFs: extracts text/tables/images, merges/splits/rotates pages, adds watermarks, creates/fills forms, encrypts/decrypts, OCRs scans. Activates on PDF mentions or output requests.
Share bugs, ideas, or general feedback.
SDK APIs change frequently. Before writing code:
https://raw.githubusercontent.com/stackoneHQ/stackone-ai-node/refs/heads/main/README.mdhttps://raw.githubusercontent.com/stackoneHQ/stackone-ai-python/refs/heads/main/README.mdhttps://docs.stackone.com/mcp/quickstartThese sources contain the latest code examples and API surface. Do not rely solely on this skill for code snippets.
| Method | Best for | Language |
|---|---|---|
TypeScript SDK (@stackone/ai) | Custom agents with OpenAI, Vercel AI, Claude, Claude Agent SDK | TypeScript/JavaScript |
Python SDK (stackone-ai) | Custom agents with LangChain, CrewAI, PydanticAI, Google ADK | Python |
| MCP Server | Claude Code, Claude Desktop, ChatGPT, Cursor, Windsurf — no code needed | Any (config only) |
| A2A Protocol | Agent-to-agent communication | Any |
Consult references/integration-guide.md for a detailed decision tree.
npm install @stackone/ai zod
import { StackOneToolSet } from "@stackone/ai";
// Initialize — reads STACKONE_API_KEY from environment
const toolset = new StackOneToolSet();
// Fetch tools for a specific linked account
const tools = await toolset.fetchTools({
accountIds: ["account-123"],
});
// Convert to your framework's format
const openaiTools = tools.toOpenAI(); // OpenAI Chat Completions
const anthropicTools = tools.toAnthropic(); // Anthropic Claude
const vercelTools = await tools.toAISDK(); // Vercel AI SDK
Tool naming: {provider}_{operation}_{entity} (e.g., bamboohr_list_employees)
Filtering tools:
const tools = await toolset.fetchTools({
providers: ["hibob", "bamboohr"], // Only these providers
actions: ["*_list_employees"], // Glob pattern matching
accountIds: ["account-123"],
});
Utility tools for dynamic discovery:
const utilityTools = await tools.utilityTools();
// tool_search — find tools by natural language query
// tool_execute — execute a discovered tool
For framework-specific integration code, fetch the GitHub README — it has complete examples for each framework.
pip install stackone-ai
Fetch the Python README for usage examples and framework integrations:
https://raw.githubusercontent.com/stackoneHQ/stackone-ai-python/refs/heads/main/README.md
The Python SDK supports: OpenAI, LangChain, CrewAI, PydanticAI, Google ADK.
StackOne's MCP server is at https://api.stackone.com/mcp.
For client-specific setup instructions, fetch the relevant guide:
https://docs.stackone.com/mcp/framework-guides/claude-codehttps://docs.stackone.com/mcp/app-guides/claude-desktophttps://docs.stackone.com/llms.txt and search for the client nameTesting the MCP connection:
npx @modelcontextprotocol/inspector https://api.stackone.com/mcp
For applications serving multiple customers, each with their own connected accounts:
// Option 1: Specify at fetch time
const tools = await toolset.fetchTools({
accountIds: ["customer-123-bamboohr"],
});
// Option 2: Change dynamically
tools.setAccountId("customer-456-bamboohr");
The accountId maps to a linked account created via the Connect Session flow (see the stackone-connect skill for setup).
User says: "I want my OpenAI agent to list employees from BambooHR"
Actions:
@stackone/ai and zodaccountIds and actions: ["bamboohr_list_employees"]tools.toOpenAI() and pass to the OpenAI chat completions callResult: Working agent that can query BambooHR employees through StackOne.
User says: "How do I use StackOne MCP in Claude Code?"
Actions:
https://docs.stackone.com/mcp/framework-guides/claude-code for the setup guidenpx @modelcontextprotocol/inspector firstResult: Claude Code can call StackOne tools directly.
User says: "Each of my customers has their own BambooHR. How do I handle that?"
Actions:
accountId when fetching toolstoolset.fetchTools({ accountIds: [customerAccountId] }) per requestResult: Understanding of the multi-tenant pattern with code to implement it.
Cause: Missing peer dependency.
@stackone/ai requires zod version >=3.25.0 <5npm install zod explicitlyCause: No tools match the filter criteria.
accountId corresponds to an active linked accountproviders filter matches exactly (e.g., bamboohr not BambooHR)Cause: Authentication misconfigured.
Authorization: Basic base64(api_key:)x-account-id header must reference a valid, active linked accountCause: Breaking changes between SDK versions.