Skip to main content

​
General Questions

The Model Context Protocol (MCP) is an open standard for connecting AI applications to external data sources and tools. It provides a standardized way for Large Language Models (LLMs) to access and interact with various services, databases, and APIs.StackOne implements MCP to give AI agents direct access to all platform actions across HRIS, ATS, CRM, and other business systems. This includes both unified operations and custom integrations created by customers, without requiring additional setup for each provider.
StackOne API:
  • Direct HTTP REST API calls
  • Requires manual integration and error handling
  • Developer builds custom tools/functions
  • Static documentation and schemas
StackOne MCP:
  • Standardized protocol for AI agents
  • Automatic tool discovery and execution
  • Built-in error handling and retries
  • Dynamic schemas and real-time capabilities
  • Optimized for AI agent consumption
MCP provides a more intelligent, agent-friendly interface to the same underlying StackOne platform actions.
StackOne supports Streamable HTTP transport only:
  • ✅ Streamable HTTP: POST/GET requests with JSON-RPC
  • ❌ Server-Sent Events (SSE): Not supported (legacy)
  • ❌ STDIO: Not applicable for cloud-hosted service
This choice provides better reliability, easier debugging, and broader client compatibility compared to SSE-based transports.

​
Setup and Configuration

See our client guides for specific setup instructions. Practically, any MCP client that supports the Streamable HTTP transport will work with StackOne MCPs.
1

Access the API Key Management Section

Log in to StackOne and go to the “API Keys” section in the left navigation menu. This is where you can generate and manage your API keys.
2

Generate a New API Key

Click the “Create API Key” button. In the popup dialog, enter a name for your key (e.g., “stackone-mcp-key”). This name is a label and cannot be changed later. Click “Generate” to create your unique API key.
3

Select API Key Scopes (optional)

By default, API keys are created with full permissions. If you need to restrict the key’s access, you can select specific scopes by expanding the “Scopes” section and selecting the scopes that match your application’s needs.
4

Securely Store the API Key

The API key will be displayed on-screen. Copy it immediately and store it securely, as this is the only time it will be shown. If you lose the key, you’ll need to generate a new one.
For complete, visual instructions on generating and managing API keys (including detailed steps & screenshots), see our API Keys guide.
Security Note: It is good practice to use different StackOne projects per environments (development, staging, production) and generate separate API keys for each.
Yes! You can configure multiple StackOne accounts in most MCP clients. Each account gets its own MCP server instance with different tools based on that account’s integrations.
Primary Method - Basic Authentication (Required):
Authorization: Basic <BASE64_ENCODED_STACKONE_API_KEY>
x-account-id: <ACCOUNT_ID>
How to encode API key:
echo -n "<stackone_api_key>" | base64
Note: Include the colon after the API keyRequired Headers:
  • Authorization: Basic auth with base64-encoded API key
  • x-account-id: Your StackOne account ID (header method recommended)
Alternative - Query Parameter:
https://api.stackone.com/mcp?account_id=<ACCOUNT_ID>
Use this for clients that don’t support the x-account-id custom header. Header method takes precedence if both are provided.See Authentication Guide for detailed setup.

​
Features and Capabilities

All StackOne platform actions are available as MCP tools, dynamically generated based on your account’s active integrations. This includes provider-specific operations, custom actions, and unified operations.
The examples below are samples only. To see the complete list of operations available for your account:Everything visible in the playground and actions pages is accessible via MCP.
Provider-Specific Actions (Sample Examples):
  • gong_crm_search_calls - Search CRM calls in Gong
  • ashby_list_applications - List applications from Ashby ATS
  • workday_list_employees - List employees from Workday HRIS
  • salesforce_list_accounts - List accounts from Salesforce CRM
  • asana_list_tickets - List tickets from Asana
  • Custom provider operations based on your connected integrations
  • And thousands more pre-built actions.
Unified Operations (Sample Examples):
  • unified_hris_list_employees - List employees (works across all HRIS providers)
  • unified_ats_list_jobs - List jobs (works across all ATS providers)
  • unified_crm_list_contacts - List contacts (works across all CRM providers)
  • and thousands more pre-built unified actions.
Custom Integrations & Actions:
  • Any integrations created by you using our Integration Engine & Integration As Code setup.
  • Custom actions built via StackOne’s action builder
  • Provider-specific operations not covered by unified APIs
Categories Supported: HRIS, ATS, CRM, Marketing Automation, IT Management, IAM, LMS, Documents, Assessments, Background Checks, Screening, Messaging, Ticketing, Accounting, and more. See all integrations.Dynamic Tool Discovery:
  • Only actions for YOUR connected providers appear
  • Actions respect your integration configuration and permissions
  • Use tools/list to see what’s available for your specific account
Yes! MCP tools provide full access to StackOne API capabilities:Supported Features:
  • ✅ All query parameters (limit, cursor, filters, etc.)
  • ✅ Request body parameters for POST/PUT operations
  • ✅ Include/expand parameters
  • ✅ Custom field access
  • ✅ Error handling
  • ✅ Pagination with cursors for unified actions
  • ✅ Real-time data by default
MCP is designed for on-demand operations, not continuous real-time sync:Good Use Cases for MCP:
  • Interactive queries (“Show me recent employees”)
  • Triggered operations (“Create employee when form submitted”)
  • Periodic operations (via scheduled workflows)
  • AI-driven data analysis and reporting
Not Optimal For:
  • Continuous real-time streaming
  • High-frequency automated syncing
  • Background data replication
For Real-Time Sync, Use Instead:
  • StackOne Unified API - Direct API calls optimized for bulk data retrieval with pagination, filtering, and updated_after parameters
  • StackOne Webhooks - Real-time change notifications when data updates in connected providers
  • Action RPC Endpoint - Direct execution of custom actions and provider-specific operations for high-frequency workflows
Hybrid Approach:
  • Use Unified API + Webhooks for continuous sync
  • Use MCP for AI-driven queries and analysis on synced data
  • Combine both for the best of real-time data and intelligent agents
For comprehensive details and examples of MCP error handling—including protocol errors, their causes, and recommended solutions—see our Troubleshooting Guide.Client Handling: Most MCP clients handle errors gracefully and can retry operations or provide alternative suggestions to users.

​
Performance and Limits

MCP operations use the same rate limits as regular StackOne API calls:Standard Limits:
  • 60 requests per minute per API key
  • 1,000 requests per hour per API key
  • 10,000 requests per day per account
Headers Returned:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200
Best Practices:
  • Use pagination to reduce large queries
  • Cache results when appropriate
  • Implement exponential backoff for retries
  • Monitor rate limit headers
Enterprise Plans: Higher rate limits available - contact StackOne support for details.
Client-Side Optimizations:
  1. Cache Tool Definitions: 
    // Cache tools list to avoid repeated calls
let cachedTools = await mcpClient.listTools();
  2. Use Appropriate Pagination: 
    {
  "limit": 25,  // Optimal batch size
  "cursor": "next_page_token"
}
  3. Connection Reuse: 
    // Reuse MCP client connections
const client = new StackOneMCPClient(apiKey, accountId);
await client.initialize(); // Once per session
Server-Side Optimizations:
  • StackOne automatically optimizes MCP responses
  • Results are compressed when possible
  • Provider connection pooling for faster operations
  • Intelligent caching where appropriate
Request Limits:
  • Maximum request size: 10MB
  • Maximum parameters per tool call: 1,000
  • Maximum nested object depth: 10 levels
Response Limits:
  • Maximum response size: 50MB (compressed)
  • Large datasets automatically paginated
  • Binary data (files) handled via streaming
Pagination Recommendations:
  • Use limit parameter to control response size
  • Default limits: 25-100 items per page
  • Maximum limit: 1,000 items per page (varies by endpoint)
For Large Operations: Consider breaking down into multiple smaller MCP tool calls rather than one large operation.

​
Development and Integration

Yes! You can create custom MCP servers that combine StackOne data with other sources:
from mcp.server import Server
from stackone import StackOneClient

app = Server("custom-stackone-mcp")
stackone = StackOneClient(api_key="...", account_id="...")

@app.tool("analyze_employee_trends")
async def analyze_trends(time_period: str) -> str:
    # Get StackOne data
    employees = await stackone.hris.list_employees(
        updated_after=get_date_filter(time_period)
    )

    # Add custom analysis
    trends = perform_custom_analysis(employees.data)

    return format_trend_report(trends)
Use Cases:
  • Combine StackOne data with internal databases
  • Add custom business logic and calculations
  • Create domain-specific abstractions
  • Implement custom caching or data transformation
For Frameworks Without Native MCP Support:
  1. Create HTTP Client Wrapper: 
    class StackOneMCPClient {
  async callTool(name: string, args: any) {
    const response = await fetch('https://api.stackone.com/mcp', {
      method: 'POST',
      headers: this.getHeaders(),
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: Date.now().toString(),
        method: 'tools/call',
        params: { name, arguments: args }
      })
    });
    return response.json();
  }
}
  2. Convert to Framework Tools: 
    // For OpenAI Functions
const tools = mcpTools.map(tool => ({
  type: 'function',
  function: {
    name: tool.name,
    description: tool.description,
    parameters: tool.inputSchema
  }
}));
  3. Handle Execution: 
    async function handleToolCall(toolCall) {
  const result = await mcpClient.callTool(
    toolCall.function.name,
    JSON.parse(toolCall.function.arguments)
  );
  return formatResult(result);
}
See our framework guides for specific examples.
Currently No Official SDK, but you can use our examples:Basic TypeScript Client:
import type { MCPRequest, MCPResponse, MCPTool } from './mcp-types';

export class StackOneMCPClient {
  constructor(
    private apiKey: string,
    private accountId: string
  ) {}

  async callTool<T = any>(
    name: string,
    arguments_: Record<string, any>
  ): Promise<T> {
    const response = await fetch('https://api.stackone.com/mcp', {
      method: 'POST',
      headers: this.getHeaders(),
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: crypto.randomUUID(),
        method: 'tools/call',
        params: { name, arguments: arguments_ }
      })
    });

    const result: MCPResponse<T> = await response.json();

    if (result.error) {
      throw new Error(result.error.message);
    }

    return this.parseContent(result.result?.content);
  }
}
Community SDKs:
  • Check npm for community-maintained packages
  • Consider contributing to open-source MCP clients
  • Use our examples as starting points
Future Plans: Official TypeScript/JavaScript SDK for MCP is under consideration.

​
Compatibility

Consider MCP if you:
  • ✅ Building AI agents or LLM applications
  • ✅ Want dynamic tool discovery
  • ✅ Need standardized AI integrations
  • ✅ Use supported MCP clients (Claude, VS Code, etc.)
  • ✅ Want reduced integration complexity
Stick with REST API if you:
  • ❌ Building traditional web/mobile applications
  • ❌ Using frameworks without MCP support
  • ❌ Have complex custom data processing needs
Hybrid Approach: Many customers use both:
  • MCP for building AI agents
  • API for other more deterministic functionality (eg. needing to render a UI on top of the data)
Yes! MCP uses the same underlying StackOne platform:Automatic Compatibility:
  • All existing provider connections work with MCP
  • Same data models and schemas for unified operations
  • Identical field mappings and transformations for unified operations
  • Same rate limits and permissions
No Changes Required:
  • Provider configurations remain the same
  • API keys work for both REST and MCP
  • Account settings apply to both interfaces
StackOne MCP servers automatically respect your integration configuration and action selection:Integration Configuration:
  • Actions must be enabled in the integration configuration associated with the linked account(s)
  • Only enabled actions appear in tools/list responses
  • This applies to both unified and provider-specific actions
Account-Level Control:
  • Actions deselected at the integration or linked account level are filtered out
  • Changes take effect immediately for all MCP clients
Example: If you disable “Create Employee” in your Workday integration configuration, the workday_create_employee tool won’t appear in MCP linked to an account using that configuration, even if the integration technically supports it.

​
Still Have Questions?

Troubleshooting Guide

Debug common issues and errors

StackOne Support

Contact support through dashboard

MCP Documentation

Official MCP protocol docs

Community Forums

Join the StackOne community