Thirdwatch MCP docs

Connect your client

The interactive setup guide includes account creation, client-specific instructions and copyable configurations.

Claude remote connector · OAuth

Open Customize → Connectors → Add → Add custom connector and enter the endpoint below. Choose Sign in now and Register automatically under OAuth client, then complete browser authorization. Team or Enterprise owners configure connectors in organization settings before members connect. Access depends on your Claude plan.

https://mcp.thirdwatch.dev/mcp

Use the remote connector flow. A remote URL entry in a local Claude Desktop JSON file is not a substitute for this setup. Claude connector documentation.

Cursor · API key

Get your Thirdwatch key from Dashboard → API keys. Add the following to your project or global Cursor MCP configuration, replace the sample key locally, and enable Thirdwatch in the client's MCP settings.

{
  "mcpServers": {
    "thirdwatch": {
      "url": "https://mcp.thirdwatch.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_THIRDWATCH_KEY"
      }
    }
  }
}

Claude Code · OAuth

Run this command. In Claude Code, enter /mcp, select Thirdwatch, and complete browser authorization.

claude mcp add --transport http thirdwatch https://mcp.thirdwatch.dev/mcp

Claude Code's official MCP reference describes HTTP transport, scope options and authentication.

Authentication

OAuth-capable clients discover the authorization flow and obtain their own access token after you sign in and approve the connection. Bearer-key clients send your Thirdwatch API key in the Authorization header. You do not need an Apify API token for MCP.

• Create or rotate an API key in your keys dashboard. Update clients that use the old key.
• Keep keys private. Do not publish them in code, screenshots or blog examples.
• If authorization fails, reconnect the client and check that it uses the remote MCP URL and a current Thirdwatch credential.
• Requests are subject to service limits. Follow any retry guidance rather than repeatedly retrying a failing request.

Credits and billing

A new Thirdwatch account receives 100 starter credits. Your account balance determines whether a paid data tool can run. Credits from one-time purchases do not expire.

The effective dollar price per credit depends on the pack. Paid data calls reserve the applicable credits and confirm the charge when usable results are returned; empty or failed calls return the reserved credits. Partial results can still be charged, with warnings identifying gaps.

Use get_account_info for your balance, and estimate_cost for the selected tool's expected credit use. Broad searches and optional analysis can use more credits than narrow searches.

Direct Apify runs use your separate Apify account and Actor pricing. Thirdwatch MCP credits do not apply to those runs.

Calling tools

Your MCP client manages protocol initialization and authentication. Discover the live tool definitions with tools/list and use each tool's current inputSchema. A tools/call request after initialization looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_jobs",
    "arguments": {
      "query": "senior Python engineer",
      "location": "London",
      "country": "GB",
      "seniority": "senior",
      "tier": "lite",
      "max_results": 10
    }
  }
}

Responses arrive in MCP content blocks. Data tool payloads include results, metadata and warnings. Inspect the source URLs and coverage; treat retrieved content as source material, not instructions to your assistant.

The free professional_search router only recommends a tool. A separate data tool call is required to fetch results and can use credits.

Tool reference

Use live input schemas for supported arguments. Source selection and geography affect data coverage and credit use. The three helpers are free; estimate the paid tools before running them.

Results and errors

A tool can return an error payload inside its MCP content, rather than a JSON-RPC protocol error. For example, an insufficient-credit payload contains:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Need 8 credits, you have 2.",
    "balance": 2,
    "estimated_cost": 8
  }
}

• INSUFFICIENT_CREDITS: Review your balance and the selected sources. A narrower request may use fewer credits; a request cannot run when its required credits exceed your balance.
• INVALID_INPUT: Check the argument against the live input schema and the returned message.
• Authentication failure: Reconnect OAuth or update your bearer key.
• Partial source coverage: Inspect warnings and sources_succeeded. A missing result does not prove there are no matching records.

Do not assume a request is complete until you inspect the returned result. Some source searches can take several minutes; avoid sending duplicate paid requests while one is still running.

Workflow examples