Skip to main content

​
Initialise the ToolSet

Start by creating a StackOneToolSet instance: 
import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet({
  baseUrl: "https://api.stackone.com",
  accountId: "your-account-id",
  search: { method: "auto", topK: 5 }, // optional: configure default search behaviour
});
The search option sets default search configuration for all searchTools() calls. Pass search: null to disable search, or omit it for the default (method: 'auto'). See Tool Search for details.

​
Fetch Tools

Use fetchTools() to dynamically load tools from StackOne’s MCP endpoint: 
// Fetch all tools for the configured account
const tools = await toolset.fetchTools();

// Or fetch with filtering options
const readOnlyTools = await toolset.fetchTools({
  actions: ['*_list_*', '*_get_*'],  // Only read operations
});
fetchTools() pulls tool definitions at runtime based on your account IDs, reusing the credentials you already configured (e.g., via STACKONE_API_KEY). This is useful for multi-tenant applications where each customer has different integrations connected.
You can filter tools by account IDs, providers, and action patterns:
// Filter by account IDs
toolset.setAccounts(['account-123', 'account-456']);
const byAccounts = await toolset.fetchTools();
// OR pass account IDs directly
const byAccountsDirect = await toolset.fetchTools({
  accountIds: ['account-123', 'account-456'],
});

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

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

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

// Combine multiple filters
const combined = await toolset.fetchTools({
  accountIds: ['account-123'],
  providers: ['hibob'],
  actions: ['*_list_*'],
});
This is useful when you want to:
  • Limit tools to specific linked accounts
  • Focus on specific providers
  • Focus on specific action or operation types (e.g., all “list” operations, create, search, etc.)

​
Execute Tools

​
Basic Tool Execution

// Get a specific tool
const employeeTool = tools.getTool('bamboohr_list_employees');

if (employeeTool) {
  // Execute with parameters
  const employees = await employeeTool.execute({
    query: { limit: 10 },
  });
  console.log(employees);
}

console.log(employees);

​
List Available Tools

// Fetch all available tools
const tools = await toolset.fetchTools();
console.log('Tools:', tools.toArray());

​
Environment Configuration

​
Using Environment Variables

// Set in your .env file
// STACKONE_API_KEY=your_api_key
// STACKONE_ACCOUNT_ID=your_account_id

const toolset = new StackOneToolSet({
  // API key and account ID are automatically read from environment
});

​
Example

​
Next Steps