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.
My own jobs is deployed for Slack and the hosted MCP server. GPT/ChatGPT and Claude client integrations remain untested and undeployed.
The hosted MCP server is deployed. The GPT / ChatGPT plugin and Claude connector are not yet tested or deployed. This guide describes the server contract for compatible MCP clients; it is not a verified ChatGPT or Claude installation guide.
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 |
Authentication is required. Do not configure anonymous access or “None” authentication. A healthy server response does not validate a client’s OAuth or tools.
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.
Client screens vary. The exact journeys in GPT/ChatGPT and Claude remain unverified.
For private job access, choose My own jobs during consent to manage jobs you created without a space. This requires an active, verified account and the requested job scopes, with no Pro requirement. If you manage exactly one eligible confirmed Pro space, you can choose that space instead. Multiple Pro spaces are not selectable yet; personal hiring remains available. A personal connection cannot read or edit any space’s jobs, even if you created those jobs. Reconnect to change the selected hiring 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. This limits volume; it does not guarantee that public listings cannot be collected.
Direct keys use their owner’s current entitlement from the API, not a Pro tier inferred from key possession. Keys belonging to a free account receive the same free limits. All of one owner’s keys share the owner’s OAuth rate-limit identity, so additional keys and rotation do not add quota. Invalid or missing entitlement metadata is refused. Key entitlement is checked on each request; OAuth’s coarse tier is captured at consent, while private-operation eligibility is checked by the server. Rate limits are approximate, not a strict global daily quota.
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. This database-backed allowance is separate from MCP discovery limits and hiring credits. If quota storage is unavailable, personal operations return 503; disconnect remains available. Respect 429 and 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:write | Job previews and commits; existing-job previews also need jobs:read. |
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 |
| Update a job | preview_job_update → update_job |
| Repost a job | preview_repost_job → repost_job |
| Unpublish a job | preview_unpublish_job → unpublish_job |
Space profile and offer writes are disabled in the current configuration. Application submission and saved jobs are not supported tools. A client’s cached tool menu does not override current server permissions.
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.
A signed preview is required by the server but does not prove that a human reviewed it. Assistants must obtain confirmation themselves; the real GPT/Claude confirmation experience remains untested. Changed content needs a new preview. A stale revision returns 409; read the job again and request confirmation for 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.
Revoked/expired credentials and disabled accounts stop access, including refresh. Losing the space management role blocks private job operations. Losing Pro blocks space-scoped private MCP access even if the client still shows those tools; discovery may continue if the account and connection remain valid. Slack and ordinary REST access do not use this same MCP Pro gate.
Failures and safe retries
| Response or symptom | Next step |
|---|---|
401 | Check authentication, expiration and revocation; reconnect when needed. |
403 | Check scopes and the selected hiring account; space access also requires the current role and Pro eligibility. An HTML security challenge is not an MCP success response. |
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.
GPT and Claude release checklist
Both client integrations remain not yet tested or deployed. Before changing that status, verify real installation, OAuth approval and cancellation, granted scopes, tool discovery, preview/confirmation, actual job results, token refresh, separate grants, role/Pro loss, revocation and reconnection. Directory publication is a separate release step. Local package tests or Worker mocks do not satisfy these checks.