> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Frequently Asked Questions

> Common questions and answers about StackOne MCP integration, features, limitations, and best practices.

## General Questions

<AccordionGroup>
  <Accordion title="What is the Model Context Protocol (MCP)?">
    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.
  </Accordion>

  <Accordion title="How does StackOne MCP differ from the regular StackOne API?">
    **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.
  </Accordion>

  <Accordion title="Which MCP transport protocols does StackOne support?">
    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.
  </Accordion>
</AccordionGroup>

## Setup and Configuration

<AccordionGroup>
  <Accordion title="Which clients support StackOne MCP?">
    See our [client guides](/mcp/app-guides/claude-desktop) for specific setup instructions. Practically, any MCP client that supports the Streamable HTTP transport will work with StackOne MCPs.
  </Accordion>

  <Accordion title="How do I get my StackOne API credentials for MCP?">
    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    <Info>
      For complete, visual instructions on generating and managing API keys (including detailed steps & screenshots), see our [API Keys guide](/guides/api-keys).
    </Info>

    **Security Note:** It is good practice to use different StackOne projects per environments (development, staging, production) and generate separate API keys for each.
  </Accordion>

  <Accordion title="Can I use MCP with multiple StackOne accounts?">
    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.
  </Accordion>

  <Accordion title="What authentication methods are supported?">
    **Primary Method - Basic Authentication (Required):**

    ```http theme={null}
    Authorization: Basic <BASE64_ENCODED_STACKONE_API_KEY>
    x-account-id: <ACCOUNT_ID>
    ```

    **How to encode API key:**

    ```bash theme={null}
    echo -n "<stackone_api_key>" | base64
    ```

    *Note: Include the colon after the API key*

    **Required 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?x-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](/mcp/auth-security) for detailed setup.
  </Accordion>
</AccordionGroup>

## Features and Capabilities

<AccordionGroup>
  <Accordion title="What StackOne operations are available through MCP?">
    **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.

    <Note>
      The examples below are **samples only**. To see the complete list of operations available for your account:

      * **Explore in Playground**: [app.stackone.com/playground](https://app.stackone.com/playground)
      * **Browse Connectors**: [app.stackone.com/connectors](https://app.stackone.com/connectors)

      Everything visible in the playground and connectors pages is accessible via MCP.
    </Note>

    **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 Connector 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](https://www.stackone.com/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
  </Accordion>

  <Accordion title="Do MCP tools support all API parameters and features?">
    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
  </Accordion>

  <Accordion title="Can I use MCP for real-time data sync?">
    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](/hris/introduction)** - Direct API calls optimized for bulk data retrieval with pagination, filtering, and `updated_after` parameters
    * **[StackOne Webhooks](/guides/webhooks)** - Real-time change notifications when data updates in connected providers
    * **[Action RPC Endpoint](/platform/api-reference/actions/make-an-rpc-call-to-an-action)** - 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
  </Accordion>

  <Accordion title="How does error handling work in MCP?">
    For details and examples of MCP error handling, including protocol errors, causes, and solutions, see our [Troubleshooting Guide](/mcp/troubleshooting).

    **Client Handling:**
    Most MCP clients handle errors gracefully and can retry operations or provide alternative suggestions to users.
  </Accordion>
</AccordionGroup>

## Performance and Limits

<AccordionGroup>
  <Accordion title="What are the rate limits for MCP operations?">
    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:**

    ```http theme={null}
    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.
  </Accordion>

  <Accordion title="How do I optimize MCP performance?">
    **Client-Side Optimizations:**

    1. **Cache Tool Definitions:**
       ```javascript theme={null}
       // Cache tools list to avoid repeated calls
       let cachedTools = await mcpClient.listTools();
       ```

    2. **Use Appropriate Pagination:**
       ```json theme={null}
       {
         "limit": 25,  // Optimal batch size
         "cursor": "next_page_token"
       }
       ```

    3. **Connection Reuse:**
       ```javascript theme={null}
       // 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
  </Accordion>

  <Accordion title="Are there size limits for MCP requests/responses?">
    **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.
  </Accordion>
</AccordionGroup>

## Development and Integration

<AccordionGroup>
  <Accordion title="Can I build custom MCP tools that use StackOne data?">
    **Yes!** You can create custom MCP servers that combine StackOne data with other sources:

    ```python theme={null}
    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
  </Accordion>

  <Accordion title="How do I implement StackOne MCP in a framework without native support?">
    **For Frameworks Without Native MCP Support:**

    1. **Create HTTP Client Wrapper:**
       ```typescript theme={null}
       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:**
       ```javascript theme={null}
       // For OpenAI Functions
       const tools = mcpTools.map(tool => ({
         type: 'function',
         function: {
           name: tool.name,
           description: tool.description,
           parameters: tool.inputSchema
         }
       }));
       ```

    3. **Handle Execution:**
       ```javascript theme={null}
       async function handleToolCall(toolCall) {
         const result = await mcpClient.callTool(
           toolCall.function.name,
           JSON.parse(toolCall.function.arguments)
         );
         return formatResult(result);
       }
       ```

    See our [framework guides](/mcp/framework-guides/vercel-ai-sdk) for specific examples.
  </Accordion>

  <Accordion title="Is there a TypeScript SDK for StackOne MCP?">
    **Currently No Official SDK**, but you can use our examples:

    **Basic TypeScript Client:**

    ```typescript theme={null}
    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.
  </Accordion>
</AccordionGroup>

## Compatibility

<AccordionGroup>
  <Accordion title="I'm using StackOne REST API - should I migrate to MCP?">
    **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)
  </Accordion>

  <Accordion title="Will my existing StackOne integrations work with MCP?">
    **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
  </Accordion>

  <Accordion title="How do I reduce context window usage with many MCP tools?">
    By default, StackOne registers each enabled action as its own MCP tool. For integrations with many actions, this can consume significant context window tokens.

    Use **search & execute mode** to keep the tool footprint constant at two tools regardless of how many actions your integration supports:

    ```
    https://api.stackone.com/mcp?tool-mode=search_execute
    ```

    This registers two tools:

    * `{provider}_search_actions` — accepts a natural language query and returns matching actions with their `action_id`
    * `{provider}_execute_action` — runs any action by its `action_id`

    The agent searches first, then executes — trading tool-list brevity for an extra round trip.

    See [Tool Modes](/mcp/tool-modes) for setup examples and when to use each mode.
  </Accordion>

  <Accordion title="How do I control which actions are available to MCP clients?">
    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.
  </Accordion>
</AccordionGroup>

## Still Have Questions?

<CardGroup cols={2}>
  <Card title="Troubleshooting Guide" icon="wrench" href="/mcp/troubleshooting">
    Debug common issues and errors
  </Card>

  <Card title="StackOne Support" icon="headset" href="https://app.stackone.com">
    Contact support through dashboard
  </Card>

  <Card title="MCP Documentation" icon="book" href="https://modelcontextprotocol.io">
    Official MCP protocol docs
  </Card>

  <Card title="Community Forums" icon="users" href="/mcp/">
    Join the StackOne community
  </Card>
</CardGroup>