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

## MCP Inspector

To watch the raw protocol exchange while debugging, run the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash theme={null}
npx @modelcontextprotocol/inspector https://api.stackone.com/mcp
```

Add your `Authorization` and `x-account-id` headers in the Inspector UI to authenticate, then inspect the tools and calls for that account.

## HTTP errors

Returned as HTTP status codes before a JSON-RPC exchange happens — almost always headers or credentials.

<AccordionGroup>
  <Accordion title="401 / 403 — Authentication failed">
    **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="400 — 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

    **Solution:** pass the account ID as a query parameter instead — `https://api.stackone.com/mcp?x-account-id=<ACCOUNT_ID>` (the header takes precedence if both are set).
  </Accordion>

  <Accordion title="406 — Not Acceptable">
    **Likely Cause:** the mandatory `Accept` header is missing or incomplete.

    **Solution:** send `Accept: application/json,text/event-stream` on **every** request — both formats listed, no wildcards. This is required by the MCP specification, not just StackOne.
  </Accordion>
</AccordionGroup>

## MCP protocol errors

Returned as JSON-RPC error objects with a `-32xxx` code.

<AccordionGroup>
  <Accordion title="-32000 — Only POST is supported">
    **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="-32603 — Tool execution failed">
    **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** against the tool's input schema

    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>

  <Accordion title="-32700 — Parse error">
    **Likely Cause:** the request body is not valid JSON.

    **Solution:** check the JSON syntax — a trailing comma, unescaped quote, or truncated body are the usual culprits.
  </Accordion>

  <Accordion title="-32600 — Invalid Request">
    **Likely Cause:** the JSON is valid but not a well-formed JSON-RPC 2.0 request.

    **Solution:** verify the request structure — it needs `jsonrpc: "2.0"`, an `id`, and a `method`.
  </Accordion>

  <Accordion title="-32601 — Method not found">
    **Likely Cause:** unknown JSON-RPC method.

    **Solution:** check the method name spelling — supported methods include `initialize`, `tools/list`, and `tools/call`.
  </Accordion>

  <Accordion title="-32602 — Invalid params">
    **Likely Cause:** the method exists but the parameters don't match its schema.

    **Solution:** validate the params against the tool's input schema from `tools/list`.
  </Accordion>
</AccordionGroup>

## No error, unexpected result

<AccordionGroup>
  <Accordion title="Tools list is empty (200 OK, no tools)">
    **Symptoms:**

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

    **Likely Causes:**

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

    **Solutions:**

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

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

## 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:"
```

For StackOne API error codes beyond MCP, see [Error Codes and Troubleshooting](/legacy-unified-apis/error-codes-and-troubleshooting).

## Related resources

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

  <Card title="FAQ" icon="question" href="/embed/call-actions/mcp/faq">
    Find answers to common questions
  </Card>
</CardGroup>