Troubleshooting - Stackone

MCP Inspector

To watch the raw protocol exchange while debugging, run the MCP Inspector:

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.

401 / 403 — Authentication failed

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

400 — 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

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

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.

MCP protocol errors

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

-32000 — Only POST is supported

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

-32603 — Tool execution failed

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 against the tool’s input schema
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": {}
  }'

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

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

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

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

No error, unexpected result

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:

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

Verify list of accounts:

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

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

For StackOne API error codes beyond MCP, see Error Codes and Troubleshooting.

Status Page

Check system status and incidents

FAQ

Find answers to common questions

​MCP Inspector

​HTTP errors

​MCP protocol errors

​No error, unexpected result

​Diagnostics

​Related resources

Status Page

FAQ

MCP Inspector

HTTP errors

MCP protocol errors

No error, unexpected result

Diagnostics

Related resources