Connect to the Coworkies MCP server
Configure the hosted MCP endpoint, choose OAuth or API-key authentication, check space eligibility and scopes, and use previews before changing jobs.
Use the Coworkies MCP server to search public listings or manage jobs from a compatible client. Coworkies does not currently offer a ChatGPT plugin or a Claude connector.
Endpoint and authentication
| Setting | Value |
|---|---|
| Endpoint | https://mcp.coworkies.com/mcp |
| Transport | Streamable HTTP |
| Authentication | OAuth account authorization, or a direct API key for discovery only |
| Health endpoint | https://mcp.coworkies.com/healthz |
Choose OAuth to connect a Coworkies account or an API key to search public listings.
OAuth account connection
- In a compatible client that supports remote Streamable HTTP and OAuth, add the endpoint above.
- Start its authorization flow and sign in to your active, verified Coworkies account.
- Review the requested scopes and space access on Coworkies. Approve only what you intend to grant, or cancel.
- Return to the client and inspect the tools actually available to the connection.
- Start with a read operation. For any write, review and confirm its preview first.
When Coworkies asks what you want to connect, choose My own jobs to manage jobs you created without a space, or choose a confirmed, open space where you are an owner or staff member. The website can show up to 20 eligible spaces. Hiring access can include a free space or one whose Pro term has ended. Funding and privileged space operations have separate requirements. Reconnect to change the selected account.
Direct API key
Configure the client’s secure header settings with either Authorization: Bearer <your-key> or X-API-Key: <your-key>. Never place the real key in a URL, shared configuration or public browser code.
This route exposes public discovery only. REST write scopes on a key do not grant private MCP tools; those require eligible OAuth authorization. Public discovery describes the data, not anonymous access. See API keys.
Discovery limits and API keys
Free OAuth accounts can discover public jobs, with a configured limit of 20 requests per minute and 10 results per page.
Your account’s plan sets the discovery limit for your API keys. Your keys and OAuth connections share that limit. Creating or rotating a key gives you no extra requests. If a request returns 429, wait for the interval in Retry-After.
Personal hiring limits and publication
Personal hiring API requests share 20 requests per minute and 1,000 per UTC day per Coworkies user across MCP and Slack connections, including identity checks. Additional credentials, reconnecting or changing Slack workspaces do not add quota. These limits are separate from MCP discovery limits and hiring credits. If you receive 429, wait for the interval in Retry-After.
Choose listing_option: "free" or "standard" in preview_job and keep the same value for create_job. Standard is the default. Free uses the existing 30-day basic listing rules, without paid promotion. Standard uses available hiring credit or remains a draft for checkout. Publication never follows from the connection alone.
Scopes and available tools
| Scope | Access |
|---|---|
mcp:read | Public discovery through OAuth. |
jobs:read | Private jobs and drafts for the selected personal account or eligible space. |
jobs:draft, jobs:publish, jobs:edit, jobs:lifecycle | Draft, publish or repost, edit, or unpublish within the selected account. Legacy jobs:write grants retain compatible actions. |
| Current connection | Use get_connection_context when offered to inspect effective permissions and available actions. |
offline_access | Refresh capability; no additional job permissions. |
| Operation | Tools |
|---|---|
| Discover public content | search_jobs, get_career_board, list_cities, find_spaces, list_events, search_articles |
| Read connected jobs, including drafts | list_my_jobs, get_my_job |
| Create a job | preview_job → create_job |
| Publish a saved draft | preview_publish_job → publish_job when available |
| Update a job | preview_job_update → update_job |
| Repost a job | preview_repost_job → repost_job |
| Unpublish a job | preview_unpublish_job → unpublish_job |
To manage space profiles, locations, media or offers, check which tools your client lists after you connect. The tools you can use depend on your role and the permissions you granted.
Preview and confirm every write
- Read the current tool schema and collect the required facts. Resolve cities through lookup results rather than guessing IDs or slugs.
contractandfreelanceare distinct job types. - Call the matching preview tool.
- Show the user the material content and consequences, including the selected hiring account, Free or Standard listing option, and publication/payment outcome.
- Obtain their confirmation before the commit tool.
- Submit the matching preview for the same user, hiring account, content and operation. Existing-job actions also require the current revision.
- Report the actual result: published, draft, payment required or failed. Complete any checkout on Coworkies.
If the content changes after confirmation, request a new preview and ask the user to confirm it. If you receive 409, read the job again before requesting the new preview.
Connection lifetime and revoked access
Access tokens last one hour. Refresh access is limited to 30 days of inactivity and 90 days total. Reauthorize when the grant expires. Each OAuth grant has its own credential, so revoking one client’s grant does not revoke another’s.
Revocation, expiry or a disabled account stops access, including refresh. Losing the management role blocks private space jobs. Loss of Pro can disable privileged space operations and pause manual space tokens. Job authority and funding are checked separately.
Failures and safe retries
| Response or symptom | Next step |
|---|---|
401 | Check authentication, expiration and revocation; reconnect when needed. |
403 | Check the action scope, current role and selected account. Privileged space operations can also require Pro. |
409 | Refresh the job and create a new preview; do not replay a stale change. |
429 | Respect Retry-After before retrying. |
Timeout, incomplete response or 5xx after a write | Reconcile through private job reads or the Coworkies dashboard before retrying; the write may already have succeeded. |
Public job discovery can lag by up to 300 seconds and space discovery by up to 1,800 seconds. Private reads are uncached. Do not infer a failed write solely from a public search result.