Troubleshooting

Check the following:

• 1.The key starts with ws_ and is copied in full (no trailing spaces).
• 2.The header format is exactly Authorization: Bearer ws_your_key.
• 3.The key has not been revoked. Check Settings → API Keys in your dashboard.
• 4.You are hitting worksignal.com, not worksignal.io (the .io domain redirects to .com - use .com directly for API calls).

• 1.Verify Node.js is installed and npx is on your PATH: run npx --version in your terminal.
• 2.Restart your AI tool after adding the MCP server config. Many tools only read config at startup.
• 3.Check that the WORKSIGNAL_API_KEY env variable is set correctly in your MCP config.
• 4.Try running the server manually to check for errors: WORKSIGNAL_API_KEY=ws_... npx @worksignal/mcp-server

The free plan allows 100 API requests per day, resetting at midnight UTC. When you hit the limit, the API returns HTTP 429 with a Retry-After header.

If you need unlimited requests, upgrade to Pro ($99/month).

• 1.Check that your subscription is active (not paused) in Settings → Webhook Subscriptions.
• 2.Use the Test button in the dashboard to send a test event and check your endpoint's response.
• 3.Confirm your endpoint is publicly accessible (not localhost). For local development, use a tunnel like ngrok or cloudflared.
• 4.Your endpoint must return a 2xx status within 10 seconds.
• 5.After 5 consecutive failures, the subscription auto-pauses. Reactivate it via the dashboard or API.

The messages array in the response body tells you exactly what failed. Common causes:

• -Title can't be blank - role.title is required.
• -Remote policy is not valid - Must be onsite, hybrid, or remote.
• -Career portal not configured - Complete your organization profile in Settings → Organization before posting publicly.