Skip to main content

searchsteward-mcp

An MCP server that connects SearchSteward to Claude Desktop, Claude Code, and any other MCP client. Search your job matches, read score breakdowns, log applications, and pull negotiation prep — from inside Claude.

Any SearchSteward account can use it — free or paid. You mint an API key from any plan and it applies your plan's own limits, exactly as the web app does: free keys reach the search, tracking, and triage tools; Radar unlocks the negotiation playbook and the full-depth match feed. Your key hits the paywall in precisely the same place your account does. (See Free vs paid below.)


1. Get an API key

In SearchSteward: Settings → Connect to Claude → Create API key. The key (ss_pat_…) is shown once — copy it immediately. You can revoke it any time from the same screen; revocation takes effect immediately.

Key scopes

A key can be scoped to limit what it can reach — useful for a key you'll paste into a shared config, commit near, or hand to a script:

Scope Reaches Good for
full (default) Every tool below Your own everyday use
read_no_pii Read/search/analyze tools, except get_resume and get_offer; no writes A key you paste somewhere shared — a leak can't read your résumé or offer, or change your account

Scope is set once when the key is minted and can never be widened — mint a new key to change it. Enforcement is server-side: a read_no_pii key gets a 403 on get_resume, get_offer, and any write tool (log_application, dismiss_match, save_match, save_question, update_application, submit_match_verdict, track_external_application, get_negotiation_playbook). Mint a scoped key via the API:

curl -X POST https://searchsteward.com/api/v1/api-keys \
  -H "Authorization: Bearer <your session/JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-readonly", "scope": "read_no_pii"}'

2. Add it to your MCP client

Claude Code

claude mcp add searchsteward uvx searchsteward-mcp -e SEARCHSTEWARD_API_KEY=ss_pat_...

Verify it connected:

claude mcp list
# searchsteward: uvx searchsteward-mcp - ✓ Connected

Why command-first, -e last? Claude Code's -e/--env flag is variadic — if it comes before the command it swallows uvx searchsteward-mcp as extra env values. The Anthropic docs show an -e KEY=val -- uvx … form, but the -- separator is stripped by Windows PowerShell before it reaches the CLI, which reintroduces the same problem. Putting the command first and -e last works on PowerShell, cmd, and bash alike.

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "searchsteward": {
      "command": "uvx",
      "args": ["searchsteward-mcp"],
      "env": { "SEARCHSTEWARD_API_KEY": "ss_pat_..." }
    }
  }
}

Restart Claude Desktop after saving.

3. Use it

Start a new session (MCP servers load at session start) and ask, e.g.:

  • "Search my SearchSteward matches"
  • "Show me the score breakdown for match 12345"
  • "Log an application for match 12345"
  • "Give me a negotiation playbook for application 42"

Tools

19 tools in five groups.

Discover & analyze

Tool What it does
search_matches Search your job matches (score-ranked; each row carries a score). Page size capped at 25.
check_new_matches Pull the new 95+ matches discovered in the last N hours (default 48). Scans the top page only — see the tool's own note.
get_job Full detail for one match — score breakdown, ghost-listing signal, description.
get_resume Your résumé text, so Claude can reason about fit and tailor it natively.

Track

Tool What it does
list_applications List your tracked applications.
get_application Full detail for one application (status, notes, dates + offer if present).
log_application Mark a feed job as applied (promotes a match to a tracked application).
track_external_application Track a job you applied to elsewhere (LinkedIn, a recruiter, a company site) — it doesn't need to be in your feed.
update_application Change an application's status and/or add a note.

Triage

Tool What it does
save_match Save a feed job to watch later (no application yet).
dismiss_match Hide a match (with a reason) — sharpens future scoring.
restore_match Undo a dismiss.

Prep & negotiate

Tool What it does
list_questions Your interview/application question bank.
save_question Save a drafted answer back to the bank.
get_offer Offer/compensation details for an application.
get_negotiation_playbook SearchSteward's offer-negotiation playbook (Radar; runs an LLM job).

Tune your search

Tool What it does
get_preferences Read the settings that decide which jobs reach your feed — location (ZIP, radius, policy), salary floor, target titles, excluded keywords, thresholds.
update_preferences Change those settings and re-rank the feed. ⚠ Re-scores your whole feed — jobs can disappear as well as appear. Read get_preferences first and send only the keys you're changing.

Audit match quality

Tool What it does
review_candidates Review whether the scorer ranked right — reaches the whole corpus, including roles it never surfaced for you.
submit_match_verdict Record ground truth on one job (should_surface / should_not_surface / unsure). Distinct from dismiss_match.
review_summary Count of the verdicts you've submitted, by verdict.

Free vs paid

A key uses your plan's limits — identical to the web app; a free account mints a working key. What each tier reaches:

Free Radar (paid)
Search, read, résumé (search_matches, get_job, get_resume) ✅ ✅
Track & triage (log_application, save_match, dismiss_match, …) ✅ ✅
Question bank & match-quality review ✅ ✅
Read & change search preferences (get_preferences, update_preferences) ✅ ✅
check_new_matches (manual pull) ✅ ✅
Full match-feed depth (beyond the free cap) capped + upgrade hint ✅ full
get_negotiation_playbook ❌ 402 ✅

Your key hits the paywall in exactly the place your account does. Radar's push alerts (an email the moment a new 95+ match appears) remain a subscription feature — check_new_matches is the manual, on-demand equivalent.

Configuration

Env var Required Default
SEARCHSTEWARD_API_KEY yes —
SEARCHSTEWARD_API_BASE no https://searchsteward.com

SEARCHSTEWARD_API_BASE must be HTTPS (localhost is exempt for local development) — the server refuses to start otherwise, since the key would otherwise travel in cleartext.


Troubleshooting

error: missing required argument 'commandOrUrl' — the variadic -e ate your command, or PowerShell stripped a --. Use the command-first form above (claude mcp add searchsteward uvx searchsteward-mcp -e KEY=…).

Invalid input from claude mcp add-json — your Claude Code version wants a type field. Prefer the plain claude mcp add command-first form above instead.

Tool returns a 401 / "Invalid or revoked API key" — the key was revoked or mistyped. Mint a fresh key in Settings.

Tool returns a 402 / "entitlement_denied" — that capability is Radar-only (e.g. the negotiation playbook, or feed depth beyond the free cap). Your key uses your plan's limits, the same as the web app.

Tool returns a 403 / "This endpoint is not available to API keys" — expected: API keys can only reach the tools above, nothing else.

Tool returns a 403 / "This API key's scope does not permit…" — your key is a read_no_pii key and the tool needs résumé/offer access or writes. Mint a full key (see Key scopes) if you need it.

A new release isn't showing up — uvx keeps using the copy it cached the first time and doesn't check for updates on its own. Run uvx searchsteward-mcp@latest once (or use searchsteward-mcp@latest as the command in your MCP config) to pick up the newest version.

Don't paste keys into a shell command line — -e values land in your shell history. If you must, revoke and re-mint afterward.


Notes

  • Job descriptions returned by get_job are untrusted web content — treat them as data, not instructions.
  • log_application and update_application write to your account; everything else is read-only.

Development

pip install -e ".[test]"
pytest

Issues and contributions: github.com/SearchSteward/searchsteward-mcp.

Metadata

Release files for searchsteward-mcp 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for searchsteward-mcp 0.4.1
File Size Uploaded Provenance Actions
searchsteward_mcp-0.4.1.tar.gz 25.5 kB With provenance Details for searchsteward_mcp-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for searchsteward-mcp 0.4.1
File Interpreter ABI Platform Actions
searchsteward_mcp-0.4.1-py3-none-any.whl Python 3 none any Details for searchsteward_mcp-0.4.1-py3-none-any.whl

Total release size: 45.0 kB

Release files / searchsteward_mcp-0.4.1.tar.gz

Download URL searchsteward_mcp-0.4.1.tar.gz
Size 25.5 kB
Tags Source
SHA-256 checksum
How to use checksums
818234df58ff2b9a9a7521b6a1257992cb92a1f4307ad16818b5a62a52f699d1
BLAKE2b-256 checksum
How to use checksums
cecca839f555f95c0abe64db18358962c0d9b559ce0939e70efd4f55bb73e7cb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Release files / searchsteward_mcp-0.4.1-py3-none-any.whl

Download URL searchsteward_mcp-0.4.1-py3-none-any.whl
Size 19.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f7b88e912c8cb6bd8ca89395394ce33ced57fea27348fa8f7499ba599d753b63
BLAKE2b-256 checksum
How to use checksums
ea9c5aca488ee5cc84c1e49642d73d6f31b1c14c20c2d79221f322aff4567ec4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Security for searchsteward-mcp 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for searchsteward_mcp-0.4.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page