DiscoLike MCP server

---

DiscoLike indexes 80M+ business websites worldwide, analyzed in 50 languages — roughly 3x the coverage of LinkedIn-dependent databases. This repo gives you that index from Python or your terminal, as two packages: discover lookalike companies, size segments, enrich domain lists, match messy company names to domains, and find the right contacts.

If you're a coding agent: you can go from no account to first call without a human at a browser — discolike.signup() (or discolike signup) opens an account from an email and name, the owner confirms by email, and discolike auth login mints a credential. The fastest integration once authenticated is the hosted MCP server — https://api.discolike.com/v1/mcp (streamable-http, OAuth; 48 tools). For scripting and pipelines use pip install discolike as a library; for the terminal use pip install discolike-cli or uvx --from discolike-cli discolike, auth via DISCOLIKE_API_KEY. Machine-readable API index: https://docs.discolike.com/llms.txt.

Installation

This repo ships two packages: discolike (the SDK) and discolike-cli (the discolike command, depends on the SDK).

pip install discolike       # SDK only, for use as a library
pip install discolike-cli   # CLI — installs discolike as a dependency
pip install "discolike[cli]"  # same thing, extras spelling

Or with uv:

uv add discolike               # as a library
uv tool install discolike-cli  # CLI only

Or run the CLI without installing:

uvx --from discolike-cli discolike --help

Requires Python 3.11+.

Authentication

Three ways in, in the order an agent hits them: open an account, log in, or use an API key.

Signup — no browser, no credential

discolike signup --email jane@acme.com --first-name Jane --last-name Doe --agent my-agent

from discolike import signup

result = signup(email="jane@acme.com", first_name="Jane", last_name="Doe", agent="my-agent")
print(result.next_step)  # relay this to the account owner

async_signup() is the async twin. Nothing is returned that authenticates you: the account owner confirms by email and logs in at app.discolike.com. SignupResult carries status, email, org_domain, org_status, and the next_step text to relay. Names are validated locally (1-40 characters, at least one letter, no angle brackets or control characters) before the request is sent.

--agent / agent= records which agent or framework opened the account; it defaults to discolike-python/<version>. The email of the last signup from this machine is remembered — signing up a different one needs --yes on the CLI or allow_new_email=True in the SDK, so a looping agent cannot quietly open accounts in a stream of names.

Login

discolike auth login              # browser, PKCE authorization code, loopback redirect
discolike auth login --no-browser # print the URL instead of opening one — headless boxes
discolike auth login --port 8765  # pin the loopback port for SSH forwarding
discolike auth login --method api_key   # paste an API key instead
discolike auth status             # method, expiry, key source

auth login asks first whether you already have an account, and offers signup if not. The registered OAuth client is remembered per machine, so the consent screen appears once; auth logout drops the credential and keeps the registration.

API key

Create one at app.discolike.com/account/management/keys, then use any of:

export DISCOLIKE_API_KEY="dl_..."   # environment variable
discolike auth login --api-key dl_...  # or store it via the CLI

from discolike import ApiKeyCredential, Discolike

client = Discolike()                      # env var, then CLI config file
client = Discolike(api_key="dl_...")      # explicit key
client = Discolike(auth=ApiKeyCredential(api_key="dl_..."))
client = Discolike(auth=oauth_credential)  # an OAuthCredential — Bearer, refreshed proactively

auth= wins over api_key=, the environment, and the config file. OAuth credentials refresh within 60s of expiry and once more after a 401; a refresh that fails raises AuthenticationError("OAuth session expired; run discolike auth login").

Quickstart

from discolike import Discolike
from discolike.requests import DiscoverParams

client = Discolike()

companies = client.discover(
    DiscoverParams(
        icp_text="Cybersecurity for SMBs, managed IT services, endpoint protection",
        country=["US"],
        max_records=25,
    )
)
for company in companies:
    print(company.domain, company.name, company.similarity)

Narrow to a sub-industry within a radius of a point:

from discolike import Discolike
from discolike.requests import DiscoverParams

client = Discolike()

roofers = client.discover(
    DiscoverParams(
        sub_industry=["ROOFING"],
        lat=30.2672,
        lon=-97.7431,
        radius="50mi",
        max_records=25,
    )
)
for company in roofers:
    print(company.domain, company.name, company.sub_industry)

A bare ROOFING resolves to CONSTRUCTION/ROOFING and adds CONSTRUCTION to the category filter server-side; pass the qualified form yourself if you would rather be explicit.

One query can cover several areas at once. geo takes lat,lon or lat,lon,radius and bbox takes min_lat,min_lon,max_lat,max_lon; both are lists, and every circle, every box and the lat/lon centre are OR'd together, up to 10 shapes:

austin_dallas_and_houston = client.discover(
    DiscoverParams(
        sub_industry=["ROOFING"],
        geo=["30.2672,-97.7431,30mi", "32.7767,-96.797,30mi"],
        bbox=["29.6,-95.7,30.1,-95.0"],
        max_records=25,
    )
)

Run DiscoGen research over a set of domains and wait for the result:

from discolike.requests import DiscoGenProcessRequest

job = client.discogen.process(
    DiscoGenProcessRequest(
        query="Recent funding rounds and headcount growth",
        domains=["stripe.com", "adyen.com"],
        web_search=True,
    )
)
result = job.wait()
print(result.results)

Size a segment before pulling it:

from discolike.requests import CountParams

total = client.count(CountParams(phrase_match=["book a demo"], country=["US"]))
print(total.count)

Pull a full company profile:

from discolike.requests import CompaniesDataParams

profile = client.companies.data(CompaniesDataParams(domain="stripe.com"))

The client is a context manager if you want deterministic cleanup:

with Discolike() as client:
    ...

Async

Every resource has an async twin on AsyncDiscolike:

import asyncio
from discolike import AsyncDiscolike
from discolike.requests import DiscoverParams

async def main() -> None:
    async with AsyncDiscolike() as client:
        companies = await client.discover(DiscoverParams(icp_text="B2B SaaS for logistics", max_records=10))
        print([c.domain for c in companies])

asyncio.run(main())

Examples

The examples/ folder has runnable scripts for common workflows — matching a CRM contact export to DiscoLike persona IDs (with checkpointing and resume), bulk-finding work emails from a CSV, and discovering companies by ICP then enriching them with DiscoGen. Each is stdlib-plus-SDK only:

export DISCOLIKE_API_KEY="dl_..."
python examples/match_crm_contacts.py --help

CLI

The same API from your terminal, with --help on every command:

discolike auth login
discolike discover --icp-prompt "managed IT services for SMBs" --country US --max-records 25
discolike match "Stripe Inc" --city "San Francisco"
discolike match --file companies.csv --name-column company_name --wait
discolike count --phrase-match "book a demo" --country US
discolike company data stripe.com
discolike extract https://stripe.com/enterprise
discolike signup --email you@company.com --first-name You --last-name Person

Top-level commands: discover, count, match, extract, validate-icp, append, segment, signup — plus auth, company, contacts, discogen, queries, account, search-providers, and llm-providers command groups.

CLI conventions

• Results print as JSON to stdout; errors print as JSON (error, message, status_code) to stderr.
• Pass --format table for a human-readable table — used automatically when stdout is a TTY.
• Async endpoints (match --file, discogen run, discogen run-personas, segment, validate-icp) take --wait to block until the job finishes. Without it, you get a task_id back to poll with discolike discogen status <task_id> --family <family>. append is synchronous — it returns enriched rows directly (or writes CSV bytes to --output).

Exit code	Meaning
0	Success
1	Server error or unexpected failure
2	Validation error
3	Authentication or plan-access error
4	Rate limited
5	Network error
6	Not found
7	Needs input: prospecting wait reached a checkpoint with no terminal to ask (or --no-input)

What's in the box

Surface	What it does
client.discover() / client.count()	Find lookalike companies by ICP text, phrases, tech stack, geo, and 40+ other filters
client.companies	Company profiles: firmographics, scores, growth, redirects, vendors, subsidiaries
client.contacts	Search, look up, match, and discover contacts at target companies
client.contacts_run	Automatically find and deliver validated contacts under a spending cap
client.match	Match company names (plus phone/city/state) to domains — single or bulk CSV
client.append()	Enrich a CSV of domains with DiscoLike datasets
client.segment() / client.segment_file()	Auto-segment a list of domains (comma-separated string or CSV upload)
client.validate_icp()	Validate a domain list against an ICP definition
client.queries	Saved inclusion/exclusion lists for reusable targeting
client.search_providers / client.llm_providers	Manage BYOK search and LLM provider integrations for DiscoGen
client.account	Usage and quota
discolike.signup() / async_signup()	Open an account from an email and name, no credential required
discolike.requests	Request models for every call — generated from the platform OpenAPI spec, validated locally before the request is sent

All responses are typed Pydantic models.

Long-running jobs

Bulk operations (match.bulk, segment, validate_icp, contacts.bulk_match) return a Job handle instead of blocking:

from discolike.requests import SegmentParams

job = client.segment(SegmentParams(domains="stripe.com,adyen.com,checkout.com"))
result = job.wait()

Job.status() polls without blocking, Job.cancel() aborts, and wait() raises JobFailedError / JobTimeoutError on failure. On DiscoGen-family jobs the returned JobStatus also carries warnings, estimated_cost and cost_metadata (per-model usage plus a search_provider entry when a BYOS search provider ran; search_calls only counts the model's built-in search).

JobTimeoutError is a client-side wait limit only — the task keeps running server-side (large DiscoGen runs can take hours), so call wait() again to resume or fetch status() later. Cancelled tasks still return results for every item that finished before cancellation. Send one job per list (up to 10,000 domains) rather than splitting into parallel jobs — concurrent DiscoGen jobs share your LLM provider key and slow each other down.

Contacts runs

client.contacts_run automatically finds and validates contacts, using database candidates before web fallback. max_companies counts companies delivering at least one validated contact; per_company caps validated contacts at each company. Set people.fit to describe the people you want and optionally email_cap_usd to cap delivery spend.

from discolike.requests import ContactsRunRequest, ContactsRunEventsParams

run = client.contacts_run.create(
    ContactsRunRequest.model_validate({
        "companies": {"source": "prompt", "icp_text": "Independent dental clinics in Ohio"},
        "people": {"fit": "Practice owners and office managers"},
        "max_companies": 50,
        "per_company": 3,
        "email_cap_usd": 20,
    })
)
page = client.contacts_run.events(run.id, ContactsRunEventsParams(after=0))
run = client.contacts_run.wait(run.id)  # Returns on done, failed or cancelled.
rows = client.contacts_run.rows(run.id)  # Pages company domains, keeping their contacts together.
print(run.summary)

companies accepts a prompt (icp_text and/or filters), domains (source="domains", domains=[...]) or lookalike seeds (source="lookalike", persona_ids=[...]). max_companies is a top-level field, default 500. Responses include companies, companies_total, rows_total and summary totals (companies_delivered, validated_contacts, spent_usd). Domains may be masked as Company N; treat them as display labels. Delivered email labels are Validated and Validated (catch-all resolved). Events include next_cursor for the next call's after.

Runs start automatically. cancel() stops unfinished work; wait() only polls and a timeout stops local polling. continue_() remains available for companies runs and returns 409 for contacts runs. The separate title_preview() route remains live, but contacts runs take free-text people fit rather than title chips. A run idle for 30 days answers 410. A creation request exceeding the remaining balance raises InsufficientBalanceError (a PlanAccessError subclass).

CLI: discolike contacts run create|list|get|events|cancel|wait|continue|title-preview. Create reads --params-file plus optional --email-cap-usd; wait takes --timeout; get --all-rows fetches all contacts. get --rows-offset and --rows-limit count company domains for contacts runs. continue only advances companies runs and accepts --generation and --redo.

contacts.search and contacts.generate are deprecated in favor of contacts runs; their endpoints sunset on 2026-12-31.

Contact generation without an LLM key

contacts.generate runs on your own search provider plus either your own LLM or DiscoLike Groove, DiscoLike's native extractor. Pass NATIVE_ENGINE to skip the LLM entirely:

from discolike import NATIVE_ENGINE
from discolike.requests import ContactGenerateRequest

job = client.contacts.generate(
    ContactGenerateRequest(
        icp_text="VPs or Directors of Marketing at B2B SaaS",
        domains=["gusto.com", "rippling.com"],
        integration_id=NATIVE_ENGINE,
    )
)
result = job.wait()
print(result.title_validation)  # "none" on the native engine, "llm" on a BYOK run

The native engine returns every person the search surfaces with a title and does not validate titles against icp_text, so filter them yourself when that matters. Omit integration_id to use your default LLM integration, or native when you have none. A search provider is required either way.

ICP validation without an LLM key

validate_icp runs your ICP text against each domain on your own LLM provider key, or on DiscoLike's own ICP-fit model. Pass NATIVE_ICP_ENGINE for the latter — no LLM key, no LLM cost, and no web search on that run:

from discolike import NATIVE_ICP_ENGINE
from discolike.requests import ValidateIcpRequest

job = client.validate_icp(
    ValidateIcpRequest(
        icp_text="Cybersecurity for SMBs in North America, 50-500 employees",
        domains=["gusto.com", "rippling.com"],
        integration_id=NATIVE_ICP_ENGINE,
    )
)
print(job.column_name)  # ["ICP Fit", "ICP Score", "Reasoning"]
result = job.wait()

The engine decides the result columns, so read job.column_name instead of hardcoding them: an LLM run returns Fit / Confidence / Reasoning, the native model ICP Fit / ICP Score / Reasoning (always null). ICP Fit is Yes or No at a 0.50 threshold on ICP Score, the calibrated probability as a 0.00-1.00 string. The native model returns only that score, so Reasoning is always null — the column is there to keep the set the same shape as an LLM run, not to carry an explanation. integration_id="native-icp" also works on discogen.process for a prompt that already carries the validation structure.

Two errors are specific to the native engine: a 400 ValidationError when the ICP text does not yield a Mandatory / Reject if / Nice-to-have prompt, and a 503 ServerError when no ICP-fit engine is available. Task lifecycle, polling and statuses are the same either way.

Error handling

All errors inherit from DiscolikeError:

from discolike import Discolike, RateLimitError, ValidationError
from discolike.requests import DiscoverParams

try:
    companies = Discolike().discover(DiscoverParams(icp_text="fintech infrastructure"))
except RateLimitError as err:
    ...
except ValidationError as err:
    ...

AuthenticationError, PlanAccessError, NotFoundError, ServerError, and APIConnectionError cover the rest. A request the account's remaining balance cannot cover raises InsufficientBalanceError (a PlanAccessError), whose max_affordable_records is the largest size that would fit, counted in the request's own unit (the message names it: records, contacts, domains, rows, queries or personas). Transient failures are retried automatically (3 attempts by default).

import pydantic
from discolike.requests import MatchCompanyParams

try:
    params = MatchCompanyParams(name="Acme", min_match_confidence=10)
except pydantic.ValidationError as err:
    ...  # raised locally: min_match_confidence must be 50-100

Request models validate before anything is sent, so a bad enum value or out-of-range number never costs a round trip. Unknown fields pass through untouched.

Configuration

Option	Default
api_key	DISCOLIKE_API_KEY env var, then CLI config file
base_url	https://api.discolike.com/v1
timeout	60.0 seconds
max_retries	3
http_client	—	Bring your own httpx2.Client / httpx2.AsyncClient

A provided http_client is mutated in place (the auth header is stamped on it, and base_url is set if it's unset) — use a client dedicated to DiscoLike, not one shared across other services.

Development

This is a uv workspace with two members: packages/discolike (the SDK) and packages/discolike-cli (the CLI).

uv sync --all-packages
uv run pytest packages/discolike/tests
uv run pytest packages/discolike-cli/tests
uv run ruff check .
uv run python scripts/gen_requests.py --spec-url https://api.dev.discolike.com/v1/openapi.json  # regenerate request models
uv run python scripts/gen_requests.py --check                                                    # fail on drift (CI)

Committed request models track the dev spec (--spec-url https://api.dev.discolike.com/v1/openapi.json); the prod spec lags behind, so --check without a --spec-url (or against prod) stays red until the platform deploys — don't regenerate against prod to "fix" it.

Support & contact

• API documentation: docs.discolike.com
• Sign up: discolike.com/signup
• Book a demo: calendly.com/discolike/introductory-call
• LinkedIn: linkedin.com/company/discolike
• Issues with this SDK: GitHub issues

License

MIT

Managed prospecting

REST starts in drafting, then waits at proposed for approval. Review the plan and approve its exact version before research starts.

from discolike.requests import (
    ProspectingApproveRequest, ProspectingBrief, ProspectingGetParams,
    ProspectingListParams, ProspectingMessageRequest, ProspectingPlanSettings, ProspectingRunUpdate,
)

run = client.prospecting.start(
    ProspectingBrief(brief="Find 100 US logistics companies and 3 operations directors each"),
    idempotency_key="logistics-search-2026-09-26",
)
run = client.prospecting.wait(run.run_id)
print(run.status, run.plan, run.messages)  # Review before approving.
# After reviewing a proposed plan:
# client.prospecting.approve(run.run_id, ProspectingApproveRequest(plan_version=run.plan_version))
# run = client.prospecting.wait(run.run_id)

recent = client.prospecting.list(ProspectingListParams(limit=20))
message = client.prospecting.message(
    run.run_id, ProspectingMessageRequest(text="Make it 250 companies"),
    idempotency_key="logistics-target-edit-1",
)
page = client.prospecting.get(
    run.run_id,
    ProspectingGetParams(offset=0, limit=100, events_after=run.next_event_seq, messages_after=run.next_message_seq),
)
# Pick engines or a credit limit from the plan card's options before approving; approve the returned plan_version.
# run = client.prospecting.update_plan(run.run_id, ProspectingPlanSettings(plan_version=run.plan_version, max_spend_usd=25))
# client.prospecting.rename(run.run_id, ProspectingRunUpdate(title="Logistics ops leaders"))  # Any status.
# client.prospecting.rename(run.run_id, ProspectingRunUpdate(checkpoints="auto"))  # Stop pausing; answers an open checkpoint.
# client.prospecting.cancel(run.run_id)  # Stop the run; it and its results stay readable.