Skip to main content

​
Common Issues

​
Connection Problems

Symptoms:
{
  "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!): 
    echo -n "<stackone_api_key>" | base64
  2. Test with cURL: 
    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
Symptoms:
{
  "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: 
    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: 
    Content-Type: application/json
Accept: application/json,text/event-stream
Symptoms:
{
  "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

​
Tool Execution Issues

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: 
    curl https://api.stackone.com/accounts \
  -u "$STACKONE_API_KEY:"
  3. Test specific operations: 
    curl https://api.stackone.com/unified/hris/employees \
  -u "$STACKONE_API_KEY:" \
  -H 'x-account-id: <ACCOUNT_ID>'
Symptoms:
{
  "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: 
    # 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": {}
  }'

​
Error Code Reference

​
MCP Protocol Errors

CodeMessageCauseSolution
-32700Parse errorInvalid JSONCheck JSON syntax
-32600Invalid RequestMalformed requestVerify request structure
-32601Method not foundUnknown methodCheck method name spelling
-32602Invalid paramsWrong parametersValidate parameter schema
-32603Internal errorServer errorCheck StackOne status, retry

​
StackOne API Errors

For comprehensive error code information, see our Unified API Error Codes and Troubleshooting Guide.

​
Network Diagnostics

# 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

Status Page

Check system status and incidents

FAQ

Find answers to common questions

Go Back to Guides

Return to MCP documentation