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

```bash
npm install @stackone/ai zod
```

```typescript
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**:
```typescript
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:
```typescript
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

```bash
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**:
```bash
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:

```typescript
// 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