stackonehq/stackone-agents

StackOne Agents — AI Integration

Important

SDK APIs change frequently. Before writing code:

1. For TypeScript: fetch https://raw.githubusercontent.com/stackoneHQ/stackone-ai-node/refs/heads/main/README.md
2. For Python: fetch https://raw.githubusercontent.com/stackoneHQ/stackone-ai-python/refs/heads/main/README.md
3. For MCP setup: fetch https://docs.stackone.com/mcp/quickstart

These sources contain the latest code examples and API surface. Do not rely solely on this skill for code snippets.

Instructions

Step 1: Choose an integration method

| 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.

Step 2a: TypeScript SDK path

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.

Step 2b: Python SDK path

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.

Step 2c: MCP Server path (no code required)

StackOne's MCP server is at https://api.stackone.com/mcp.

For client-specific setup instructions, fetch the relevant guide:

• Claude Code: https://docs.stackone.com/mcp/framework-guides/claude-code
• Claude Desktop: https://docs.stackone.com/mcp/app-guides/claude-desktop
• Other clients: fetch https://docs.stackone.com/llms.txt and search for the client name

Testing the MCP connection:

npx @modelcontextprotocol/inspector https://api.stackone.com/mcp

Step 3: Handle multi-tenant access

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).

Examples

Example 1: User wants to add StackOne to an OpenAI agent

User says: "I want my OpenAI agent to list employees from BambooHR"

Actions:

1. Confirm they have a StackOne API key and a linked BambooHR account
2. Install @stackone/ai and zod
3. Fetch tools with accountIds and actions: ["bamboohr_list_employees"]
4. Convert with tools.toOpenAI() and pass to the OpenAI chat completions call
5. Fetch the TypeScript GitHub README for the complete OpenAI example

Result: Working agent that can query BambooHR employees through StackOne.

Example 2: User wants to set up MCP with Claude Code

User says: "How do I use StackOne MCP in Claude Code?"

Actions:

1. Fetch https://docs.stackone.com/mcp/framework-guides/claude-code for the setup guide
2. Walk through adding the MCP server config with their API key and account ID
3. Test with npx @modelcontextprotocol/inspector first

Result: Claude Code can call StackOne tools directly.

Example 3: User is building a multi-tenant SaaS

User says: "Each of my customers has their own BambooHR. How do I handle that?"

Actions:

1. Explain the account-per-customer model: each customer links their own BambooHR via Connect Sessions
2. Show how to pass the customer's accountId when fetching tools
3. Recommend using toolset.fetchTools({ accountIds: [customerAccountId] }) per request

Result: Understanding of the multi-tenant pattern with code to implement it.

Troubleshooting

Error: "Cannot find module 'zod'"

Cause: Missing peer dependency.

• @stackone/ai requires zod version >=3.25.0 <5
• Run npm install zod explicitly

fetchTools returns empty array

Cause: No tools match the filter criteria.

• Check that the accountId corresponds to an active linked account
• Verify the provider name in providers filter matches exactly (e.g., bamboohr not BambooHR)
• Try without filters first to see all available tools

MCP server returns 401

Cause: Authentication misconfigured.

• MCP uses Basic auth: Authorization: Basic base64(api_key:)
• The x-account-id header must reference a valid, active linked account
• Test with MCP Inspector to isolate auth vs. config issues

SDK version mismatch with framework

Cause: Breaking changes between SDK versions.

• Always fetch the latest GitHub README for current compatibility
• Pin specific SDK versions in production
• Check the npm/PyPI changelog for migration guides