Troubleshooting

Common Issues

Connection Problems

Authentication Error

Symptoms:

{
  "error": "Invalid authentication token"
}

Likely Causes:

Incorrect API key
Wrong base64 encoding
Expired or disabled API key

Solutions:

Verify API key encoding (include colon!):
echo -n "<stackone_api_key>" | base64

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":{}}}'

Check account ID format:
- Numeric string (e.g., 47187425466113776871)
- Or short alphanumeric ID (nano ID)
- Must have been initially created in the Stackone Dashboard
Verify API key permissions:
- Ensure key has access to required scopes

Wrong HTTP Method

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:

Always use POST method:

fetch('https://api.stackone.com/mcp', {
  method: 'POST',  // Always POST
  headers: { /* ... */ },
  body: JSON.stringify({ /* ... */ })
})

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

Include required headers:

Content-Type: application/json
Accept: application/json,text/event-stream

Missing x-account-id Header

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

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:

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

Verify list of accounts:

curl https://api.stackone.com/accounts \
  -u "$STACKONE_API_KEY:"

Test specific operations:

curl https://api.stackone.com/unified/hris/employees \
  -u "$STACKONE_API_KEY:" \
  -H 'x-account-id: <ACCOUNT_ID>'

Tool Execution Fails

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:

Validate parameters:
Check rate limits:
- Monitor X-RateLimit headers in responses
- Implement exponential backoff
- Reduce request frequency

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

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.

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

Getting Started

SDKs & Frameworks

Applications & IDEs

API Behavior

Support

Common Issues

Connection Problems

Tool Execution Issues

Error Code Reference

MCP Protocol Errors

StackOne API Errors

Network Diagnostics

Next Steps

Status Page

FAQ

Go Back to Guides

​Common Issues

​Connection Problems

​Tool Execution Issues

​Error Code Reference

​MCP Protocol Errors

​StackOne API Errors

​Network Diagnostics

​Next Steps

Status Page

FAQ

Go Back to Guides

Common Issues

Connection Problems

Tool Execution Issues

Error Code Reference

MCP Protocol Errors

StackOne API Errors

Network Diagnostics

Next Steps