docs · for agents

MCP server

ThreadSonar exposes your leads as an MCP (Model Context Protocol) server, so any agent that speaks MCP can pull qualified, intent-scored leads and action them: Claude Code, Claude Desktop, Cursor, or your own agent built on any MCP client library. The loop an agent runs is simple: poll for new hot leads, act on each one, mark it contacted so the human inbox stays in sync.

Endpoint & auth

The server speaks Streamable HTTP and is stateless: every request is authenticated with a workspace API key, created in Settings. Keys are scoped to one workspace; an agent working three products uses three keys.

endpoint

https://www.threadsonar.com/api/mcp
Authorization: Bearer tsnr_...

Connect from Claude Code

terminal

claude mcp add --transport http threadsonar https://www.threadsonar.com/api/mcp \
  --header "Authorization: Bearer tsnr_YOUR_KEY"

Connect from Claude Desktop, Cursor, or any client

mcp config (JSON)

{
  "mcpServers": {
    "threadsonar": {
      "type": "http",
      "url": "https://www.threadsonar.com/api/mcp",
      "headers": {
        "Authorization": "Bearer tsnr_YOUR_KEY"
      }
    }
  }
}

Tools

tool	what it does
`get_leads`	Fetch qualified leads: post content, author, platform URL, intent score (0-100), band (hot/warm/review), a why-it-matched rationale, and a ready-to-send reply draft when available. Filters: `signal_id`, `status`, `band`, `since` (ISO 8601), `sort` (newest / oldest / score), `limit` (max 50).
`get_lead`	Full detail for one lead: untruncated content, thread context, draft variants, enriched contact, current status.
`list_signals`	The workspace's listening signals, with ids for filtering get_leads.
`set_signal_status`	Pause or resume a signal remotely. Draft signals still need compilation in the app first.
`mark_lead`	Set a lead's status after acting on it: `contacted`, `saved`, or `dismissed`. This is what keeps the human inbox in sync with agent work.
`rate_lead`	The same 👍/👎 as the human inbox, feeding the tuning loop. `good` confirms a match; `not_relevant` refunds the lead's quota credit, removes its content, and is irreversible, so agents should use it only when confident, with a `reason`.
`get_workspace`	Workspace name, plan, and lead quota usage for the current period.
`get_playbook`	The out-of-the-box playbook: the workspace's current signal list plus the recommended loop. Agents should call it at the start of every session; it regenerates on each call, so it doubles as the way to refresh the signal list.
`enrich_lead`	LinkedIn leads only: resolves the author to a verified contact (name, title, seniority, company, verified business email) via a multi-vendor waterfall. Cached per lead, so repeat calls are free. Available when contact enrichment is enabled for the deployment.

The agent loop

You don't need to design the loop yourself: the server ships it. get_playbook returns a ready-to-follow playbook containing the workspace's live signal list and the recommended cadence, and the same text is exposed as the MCP prompt playbook for clients that surface prompts. A minimal agent brief is just:

agent instructions

You work leads from ThreadSonar.
At the start of each session, call get_playbook on the
threadsonar MCP server and follow it. It covers everything:
refreshing the signal list, polling for new hot leads,
using reply drafts, enriching LinkedIn leads to verified
contacts, and marking leads contacted when done.

Because the playbook regenerates on every call, an agent that re-reads it always sees signals the team added, paused, or renamed since the last session; no redeploys or prompt edits needed.

Good citizenship

Leads are pushed as they qualify, so polling more often than every few minutes buys nothing. Statuses and ratings are shared with the human inbox: a lead your agent marks contacted or rates good shows up that way for the whole team, and a not_relevant rating is final for everyone; the refund fires and the content is gone.

Machine-readable index

Agents exploring the site cold should fetch /llms.txt (the discovery index) and /llms-full.txt (the complete reference, generated from the same tool definitions this server ships, so it is always current). Point a crawling agent at either and it has everything on this page.

Errors

status	meaning
401	Missing, invalid, or revoked API key.
403	The key's workspace has no active plan.
tool error	Bad arguments or an unknown id; the tool result carries isError with a message.