> ## 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.

# Troubleshooting

> Common issues, error messages, and solutions for StackOne MCP integration across different clients and frameworks.

## Common Issues

### Connection Problems

<AccordionGroup>
  <Accordion title="Authentication Error">
    **Symptoms:**

    ```json theme={null}
    {
      "error": "Invalid authentication token"
    }
    ```

    **Likely Causes:**

    * Incorrect API key
    * Wrong base64 encoding
    * Expired or disabled API key

    **Solutions:**

    1. **Verify API key encoding (include colon!):**
       ```bash theme={null}
       echo -n "<stackone_api_key>" | base64
       ```

    2. **Test with cURL:**
       ```bash theme={null}
       curl -X POST https://api.stackone.com/mcp \
         -H 'Authorization: Basic <BASE64_TOKEN>' \
         -H 'x-account-id: <ACCOUNT_ID>' \
         -H 'Content-Type: application/json' \
         -H 'Accept: application/json,text/event-stream' \
         -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0.0"},"protocolVersion":"2025-06-18","capabilities":{}}}'
       ```

    3. **Check account ID format:**
       * Numeric string (e.g., `47187425466113776871`)
       * Or short alphanumeric ID (nano ID)
       * Must have been initially created in the Stackone Dashboard

    4. **Verify API key permissions:**
       * Ensure key has access to required scopes
  </Accordion>

  <Accordion title="Wrong HTTP Method">
    **Symptoms:**

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "error": {
        "code": -32000,
        "message": "Only POST is supported for stateless MCP."
      },
      "id": null
    }
    ```

    **Likely Causes:**

    * Using GET instead of POST
    * Incorrect HTTP method

    **Solutions:**

    1. **Always use POST method:**
       ```javascript theme={null}
       fetch('https://api.stackone.com/mcp', {
         method: 'POST',  // Always POST
         headers: { /* ... */ },
         body: JSON.stringify({ /* ... */ })
       })
       ```

    2. **Check endpoint URL:**
       * Must be exactly `https://api.stackone.com/mcp`
       * No trailing slashes or additional paths

    3. **Include required headers:**
       ```http theme={null}
       Content-Type: application/json
       Accept: application/json,text/event-stream
       ```
  </Accordion>

  <Accordion title="Missing x-account-id Header">
    **Symptoms:**

    ```json theme={null}
    {
      "statusCode": 400,
      "message": "Missing x-account-id header in request",
      "timestamp": "2025-10-27T23:20:13.335Z"
    }
    ```

    **Likely Causes:**

    * Client doesn't support custom headers
    * Header not configured correctly
    * MCP client limitations
  </Accordion>
</AccordionGroup>

### Tool Execution Issues

<AccordionGroup>
  <Accordion title="Tools List Empty">
    **Symptoms:**

    * `tools/list` returns empty array
    * MCP server connects but no tools available
    * Client shows "No tools found"

    **Likely Causes:**

    * Account's integration configuration is incorrect or does not have any actions enabled
    * Account configuration issues

    **Solutions:**

    1. **Check integrations in StackOne dashboard:**
       * Verify the account ID is correct and is active
       * Ensure the associated integrations configuration has at least 1 action enabled

    2. **Verify list of accounts:**
       ```bash theme={null}
       curl https://api.stackone.com/accounts \
         -u "$STACKONE_API_KEY:"
       ```

    3. **Test specific operations:**
       ```bash theme={null}
       curl https://api.stackone.com/unified/hris/employees \
         -u "$STACKONE_API_KEY:" \
         -H 'x-account-id: <ACCOUNT_ID>'
       ```
  </Accordion>

  <Accordion title="Tool Execution Fails">
    **Symptoms:**

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "error": {
        "code": -32603,
        "message": "Tool execution failed"
      }
    }
    ```

    **Likely Causes:**

    * Invalid tool parameters
    * Provider connection issues
    * Rate limiting
    * Provider-specific errors

    **Solutions:**

    1. **Validate parameters:**

    2. **Check rate limits:**
       * Monitor X-RateLimit headers in responses
       * Implement exponential backoff
       * Reduce request frequency

    3. **Test provider connection:**
       ```bash theme={null}
       # Test underlying API action via RPC
       curl -X POST https://api.stackone.com/actions/rpc \
         -u "$STACKONE_API_KEY:" \
         -H 'x-account-id: <ACCOUNT_ID>' \
         -H 'Content-Type: application/json' \
         -d '{
           "action": "<provider_action_name>",
           "query": {}
         }'
       ```
  </Accordion>
</AccordionGroup>

## Error Code Reference

### MCP Protocol Errors

| Code   | Message          | Cause             | Solution                     |
| ------ | ---------------- | ----------------- | ---------------------------- |
| -32700 | Parse error      | Invalid JSON      | Check JSON syntax            |
| -32600 | Invalid Request  | Malformed request | Verify request structure     |
| -32601 | Method not found | Unknown method    | Check method name spelling   |
| -32602 | Invalid params   | Wrong parameters  | Validate parameter schema    |
| -32603 | Internal error   | Server error      | Check StackOne status, retry |

### StackOne API Errors

For comprehensive error code information, see our [Unified API Error Codes and Troubleshooting Guide](/guides/unified-api-error-codes-and-troubleshooting-guide).

### Network Diagnostics

```bash theme={null}
# Test connectivity
curl -I https://api.stackone.com/mcp

# Check DNS resolution
nslookup api.stackone.com

# Test authentication
curl https://api.stackone.com/accounts \
  -u "$STACKONE_API_KEY:"
```

## Next Steps

<CardGroup cols={3}>
  <Card title="Status Page" icon="signal" href="https://status.stackone.com">
    Check system status and incidents
  </Card>

  <Card title="FAQ" icon="question" href="/mcp/faq">
    Find answers to common questions
  </Card>

  <Card title="Go Back to Guides" icon="arrow-left" href="/mcp/">
    Return to MCP documentation
  </Card>
</CardGroup>