Skip to main content
llms.txt

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

SettingValue
Endpointhttps://mcp.coworkies.com/mcp
TransportStreamable HTTP
AuthenticationOAuth account authorization, or a direct API key for discovery only
Health endpointhttps://mcp.coworkies.com/healthz

Choose OAuth to connect a Coworkies account or an API key to search public listings.

OAuth account connection

  1. In a compatible client that supports remote Streamable HTTP and OAuth, add the endpoint above.
  2. Start its authorization flow and sign in to your active, verified Coworkies account.
  3. Review the requested scopes and space access on Coworkies. Approve only what you intend to grant, or cancel.
  4. Return to the client and inspect the tools actually available to the connection.
  5. 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

ScopeAccess
mcp:readPublic discovery through OAuth.
jobs:readPrivate jobs and drafts for the selected personal account or eligible space.
jobs:draft, jobs:publish, jobs:edit, jobs:lifecycleDraft, publish or repost, edit, or unpublish within the selected account. Legacy jobs:write grants retain compatible actions.
Current connectionUse get_connection_context when offered to inspect effective permissions and available actions.
offline_accessRefresh capability; no additional job permissions.
OperationTools
Discover public contentsearch_jobs, get_career_board, list_cities, find_spaces, list_events, search_articles
Read connected jobs, including draftslist_my_jobs, get_my_job
Create a jobpreview_job → create_job
Publish a saved draftpreview_publish_job → publish_job when available
Update a jobpreview_job_update → update_job
Repost a jobpreview_repost_job → repost_job
Unpublish a jobpreview_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

  1. Read the current tool schema and collect the required facts. Resolve cities through lookup results rather than guessing IDs or slugs. contract and freelance are distinct job types.
  2. Call the matching preview tool.
  3. Show the user the material content and consequences, including the selected hiring account, Free or Standard listing option, and publication/payment outcome.
  4. Obtain their confirmation before the commit tool.
  5. Submit the matching preview for the same user, hiring account, content and operation. Existing-job actions also require the current revision.
  6. 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 symptomNext step
401Check authentication, expiration and revocation; reconnect when needed.
403Check the action scope, current role and selected account. Privileged space operations can also require Pro.
409Refresh the job and create a new preview; do not replay a stale change.
429Respect Retry-After before retrying.
Timeout, incomplete response or 5xx after a writeReconcile 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.

See Permissions and Integration availability and support.