Mount the agency
inside your agent.

STEP 1 · GET A KEY

Create an API key from the dashboard. Keys look like this and travel in the X-API-Key header:

gum_live_4f2a...

STEP 2 · MOUNT IT · CLAUDE CODE

claude mcp add gumshoe \
  --transport http \
  https://gumshoe.run/mcp \
  --header "X-API-Key: gum_your_key"

STEP 2 (BIS) · CLAUDE DESKTOP OR CURSOR

{
  "mcpServers": {
    "gumshoe": {
      "url": "https://gumshoe.run/mcp",
      "headers": { "X-API-Key": "gum_your_key" }
    }
  }
}

STEP 3 · THE TOOLS YOUR AGENT GETS

draft_brief

hunch (required)

Turns one sloppy sentence into a structured brief: target, signals to check, sources, output shape, plus a ready to send brief and a JSON schema. Free, spends no credits. Start here when the request is fuzzy.

file_case

url (required) · brief (required) · schema (optional) · depth (optional: read | deep) · fieldwork (optional, default false) · wait (optional, default true)

Opens an investigation and, by default, returns the closed report in the same call. 1 credit to read, 15 for a deep dossier, 42 with fieldwork: true, which authorizes the cloud browser, caps it at 15 steps, and returns its screenshots as exhibit URLs. Pass a JSON schema and the report comes back typed your way. Set wait: false to get a case_id immediately instead.

get_report

case_id (required)

Fetches the report: verdict, confidence, evidence, meter, exhibits. Returns status: working if the case is still open.

file_sweep

brief (required) · count (required, 1 to 100) · schema (optional) · wait (optional, default true)

Builds a list from scratch in one call. We fan out the searches, verify every candidate, and dedupe server-side by domain. Billed one credit per unique row delivered: duplicates and undelivered rows are refunded. Paid plans only.

list_cases

status (optional: working | closed | failed) · limit (optional, 1 to 100)

Lists your recent cases with their statuses. Handy when your agent files a batch and comes back later.

FIELD EXAMPLE · WHAT IT LOOKS LIKE IN PRACTICE

You: "Qualify the 40 signups from last night
      against our ICP. Flag anyone hiring SDRs."

Your agent: turns that into a brief with
            draft_brief, files 40 cases via
            file_case (wait: false), checks
            back with list_cases, pulls the
            verdicts via get_report, then
            updates your CRM.

You: read the flagged accounts over coffee.

RATE LIMITS · PER MINUTE, PER KEY

Published, not discovered in production. Every number below is read straight from the code that enforces it, so this table cannot drift from what the API actually does. The ceiling climbs with your rung.

A batch call carries up to 250 URLs, so 50 batch calls a minute is 12,500 URLs a minute of headroom. Past those ceilings we move you to a dedicated cluster: write to team@cclabs.cx with the volume you are aiming at, and bring your latency target with you.

HOUSE RULES

• Billing is identical to the REST API: 1 credit per URL read, 15 for a deep dossier, 42 for browser fieldwork, and only when your agent asks for it. draft_brief is free.
• Reports are bounded: a verdict plus the quotes it relied on. A sweep is many cases filed in parallel, deduped by domain before anything is billed.
• A case that finds nothing readable is refunded, and so is any sweep row we could not deliver. You never pay for an empty file.
• Every response carries its own meter: X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 adds Retry-After in seconds, so your agent knows exactly how long to breathe instead of guessing.