StackOne AI SDK

A unified interface for performing actions on SaaS tools through AI-friendly APIs.

StackOneToolSet

The StackOne AI SDK provides the StackOneToolSet class, which fetches tools dynamically from StackOne's MCP (Model Context Protocol) endpoint. This ensures you always have access to the latest tool definitions.

Installation

# Using npm
npm install @stackone/ai

# Using yarn
yarn add @stackone/ai

# Using pnpm
pnpm add @stackone/ai

Optional: AI SDK Integration

If you plan to use the AI SDK integration (Vercel AI SDK), install it separately:

# Using npm
npm install ai

# Using yarn
yarn add ai

# Using pnpm
pnpm add ai

Development Environment

Using Nix Flake

This project includes a Nix flake for reproducible development environments. If you have Nix installed with flakes enabled, you can use it to set up your development environment:

# Enter development shell
nix develop

# Or use direnv for automatic activation
echo "use flake" > .envrc
direnv allow

The flake provides all necessary development dependencies including Node.js, pnpm, and other build tools.

Integrations

The StackOneToolSet makes it super easy to use StackOne APIs as tools in your AI applications.

With OpenAI library

import { OpenAI } from "openai";
import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet({
  baseUrl: "https://api.stackone.com",
});

const tools = await toolset.fetchTools({
  actions: ["hris_*"],
});

await openai.chat.completions.create({
  model: "gpt-5.1",
  messages: [
    {
      role: "system",
      content: "You are a helpful HR assistant.",
    },
    {
      role: "user",
      content: "Create a time-off request for employee id cxIQ5764hj2",
    },
  ],
  tools: tools.toOpenAI(),
});

View full example

AI SDK by Vercel

import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";
import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet({
  baseUrl: "https://api.stackone.com",
});

const tools = await toolset.fetchTools({
  actions: ["hris_*"],
});

await generateText({
  model: openai("gpt-5.1"),
  tools: await tools.toAISDK(),
  maxSteps: 3,
});

View full example

Usage

import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet({
  baseUrl: "https://api.stackone.com",
});

const tools = await toolset.fetchTools();
const employeeTool = tools.getTool("hris_list_employees");
const employees = await employeeTool.execute();

View full example

Authentication

Set the STACKONE_API_KEY environment variable:

export STACKONE_API_KEY=<your-api-key>

or load from a .env file using your preferred environment variable library.

Account IDs

StackOne uses account IDs to identify different integrations. You can specify the account ID at different levels:

import { StackOneToolSet } from "@stackone/ai";

// Method 1: Set at toolset initialisation
const toolset = new StackOneToolSet({ accountId: "your-account-id" });

// Method 2: Use setAccounts for filtering when fetching
toolset.setAccounts(["account-123", "account-456"]);
const tools = await toolset.fetchTools();

// Method 3: Set directly on a tool instance
tools.setAccountId("direct-account-id");
const currentAccountId = tools.getAccountId(); // Get the current account ID

View full example

Features

Filtering Tools with fetchTools()

You can filter tools by account IDs, providers, and action patterns:

// Filter by account IDs
toolset.setAccounts(["account-123", "account-456"]);
const tools = await toolset.fetchTools();
// OR
const tools = await toolset.fetchTools({
  accountIds: ["account-123", "account-456"],
});

// Filter by providers
const tools = await toolset.fetchTools({ providers: ["hibob", "bamboohr"] });

// Filter by actions with exact match
const tools = await toolset.fetchTools({
  actions: ["hibob_list_employees", "hibob_create_employees"],
});

// Filter by actions with glob patterns
const tools = await toolset.fetchTools({ actions: ["*_list_employees"] });

// Combine multiple filters
const tools = await toolset.fetchTools({
  accountIds: ["account-123"],
  providers: ["hibob"],
  actions: ["*_list_*"],
});

This is especially useful when you want to:

• Limit tools to specific linked accounts
• Focus on specific HR/CRM/ATS providers
• Get only certain types of operations (e.g., all "list" operations)

View full example

Meta Tools (Beta)

Meta tools enable dynamic tool discovery and execution, allowing AI agents to search for relevant tools based on natural language queries without hardcoding tool names.

⚠️ Beta Feature: Meta tools are currently in beta and the API may change in future versions.

How Meta Tools Work

Meta tools provide two core capabilities:

1. Tool Discovery (meta_search_tools): Search for tools using natural language queries
2. Tool Execution (meta_execute_tool): Execute discovered tools dynamically

Basic Usage

import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet({
  baseUrl: "https://api.stackone.com",
});
const tools = await toolset.fetchTools();

// Get meta tools for dynamic discovery
const metaTools = await tools.metaTools();

// Use with OpenAI
const openAITools = metaTools.toOpenAI();

// Use with AI SDK
const aiSdkTools = await metaTools.toAISDK();

Example: Dynamic Tool Discovery with AI SDK

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai("gpt-5.1"),
  tools: aiSdkTools,
  prompt: "Find tools for managing employees and create a time off request",
  maxSteps: 3, // Allow multiple tool calls
});

Direct Usage Without AI

// Step 1: Discover relevant tools
const filterTool = metaTools.getTool("meta_search_tools");
const searchResult = await filterTool.execute({
  query: "employee time off vacation",
  limit: 5,
  minScore: 0.3, // Minimum relevance score (0-1)
});

// Step 2: Execute a discovered tool
const executeTool = metaTools.getTool("meta_execute_tool");
const result = await executeTool.execute({
  toolName: "hris_create_time_off",
  params: {
    employeeId: "emp_123",
    startDate: "2024-01-15",
    endDate: "2024-01-19",
  },
});

View full example

Custom Base URL

import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet({ baseUrl: "https://api.example-dev.com" });

View full example

Testing with dryRun

You can use the dryRun option to return the api arguments from a tool call without making the actual api call:

import { StackOneToolSet } from "@stackone/ai";

// Initialise the toolset
const toolset = new StackOneToolSet({
  baseUrl: "https://api.stackone.com",
});

const tools = await toolset.fetchTools();
const employeeTool = tools.getTool("hris_list_employees");

// Use dryRun to see the request details
const dryRunResult = await employeeTool.execute(
  { query: { limit: 5 } },
  { dryRun: true }
);

console.log(dryRunResult);
// {
//   url: "https://api.stackone.com/actions/rpc",
//   method: "POST",
//   headers: { ... },
//   body: "...",
//   mappedParams: { ... }
// }

The dryRun option returns an object containing:

• url: The full URL with query parameters
• method: The HTTP method
• headers: The request headers
• body: The request body
• mappedParams: The parameters after mapping and derivation

Feedback Collection Tool

The StackOne AI SDK includes a built-in feedback collection tool (meta_collect_tool_feedback) that allows users to provide feedback on their experience with StackOne tools. This tool is automatically included when using fetchTools() and helps improve the SDK based on user input.

How It Works

The feedback tool:

• Requires explicit user consent before submitting feedback
• Collects user feedback about their experience with StackOne tools
• Tracks tool usage by recording which tools were used
• Submits to StackOne via the /ai/tool-feedback endpoint
• Uses the same API key as other SDK operations for authentication

Usage

The feedback tool is automatically available when using StackOneToolSet:

import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet({
  baseUrl: "https://api.stackone.com",
});
const tools = await toolset.fetchTools();

// The feedback tool is automatically included
const feedbackTool = tools.getTool("meta_collect_tool_feedback");

// Use with AI agents - they will ask for user consent first
const openAITools = tools.toOpenAI();
// or
const aiSdkTools = await tools.toAISDK();

Manual Usage

You can also use the feedback tool directly:

// Get the feedback tool
const feedbackTool = tools.getTool("meta_collect_tool_feedback");

// Submit feedback (after getting user consent)
const result = await feedbackTool.execute({
  feedback: "The tools worked great! Very easy to use.",
  account_id: "acc_123456",
  tool_names: ["hris_list_employees", "hris_create_time_off"],
});

Multiple Account Support

The feedback tool supports both single and multiple account IDs. When you provide an array of account IDs, the feedback will be sent to each account individually:

// Single account ID (string)
await feedbackTool.execute({
  feedback: "The tools worked great! Very easy to use.",
  account_id: "acc_123456",
  tool_names: ["hris_list_employees", "hris_create_time_off"],
});

// Multiple account IDs (array)
await feedbackTool.execute({
  feedback: "The tools worked great! Very easy to use.",
  account_id: ["acc_123456", "acc_789012"],
  tool_names: ["hris_list_employees", "hris_create_time_off"],
});

Response Format: When using multiple account IDs, the tool returns a summary of all submissions:

{
  message: "Feedback sent to 2 account(s)",
  total_accounts: 2,
  successful: 2,
  failed: 0,
  results: [
    {
      account_id: "acc_123456",
      status: "success",
      result: { message: "Feedback successfully stored", ... }
    },
    {
      account_id: "acc_789012",
      status: "success",
      result: { message: "Feedback successfully stored", ... }
    }
  ]
}

AI Agent Integration

When AI agents use this tool, they will:

1. Ask for user consent: "Are you ok with sending feedback to StackOne?"
2. Collect feedback: Get the user's verbatim feedback
3. Track tool usage: Record which tools were used in the session
4. Submit to all accounts: Send the same feedback to each account ID provided
5. Report results: Show which accounts received the feedback successfully

The tool description includes clear instructions for AI agents to always ask for explicit user consent before submitting feedback.