Find Service Providers

find-service-providers

Overview

Drive the ServiceGraph API (https://api.servicegraph.co) to find, shortlist, and enrich US professional-services firms.

The API hosts several datasets behind a uniform per-dataset URL shape (/v1/datasets/:id/…). This skill is for the agencies dataset — dataset id pro_services — which holds 100k+ B2B service firms classified across 22 industries with multi-tag service taxonomies, location, size, and third-party rating signals.

Any HTTP client works (curl, fetch, requests). Examples below use curl.

Prerequisites

• ServiceGraph access, either:
  • the ServiceGraph MCP server (https://mcp.servicegraph.co) loaded in your harness — this plugin's .mcp.json wires it up; OAuth 2.1 + PKCE keeps credentials in the harness sandbox — or
  • a ServiceGraph API key (vk_…, minted at https://servicegraph.co/profile/api-keys) available as SERVICEGRAPH_API_KEY in the environment or .env.local for the REST path (setup steps under Auth below).
• An HTTP client for the REST path — the examples use curl.

Instructions

The loop is free-first: discovery, validation, search, and brief reads cost nothing; only unlock after the user confirms the spend.

1. Pick the call path — the ServiceGraph MCP tools if loaded, otherwise the REST flow (MCP server and Auth sections below).
2. GET /v1/datasets/pro_services/fields?include_values=1 — confirm the fields and values you plan to filter on exist.
3. Build the filter (Filter DSL below) and validate it with GET /v1/datasets/pro_services/check — or draft it from plain English via POST /v1/datasets/pro_services/translate-intent.
4. GET /v1/datasets/pro_services/search — present the free brief cards and let the user pick.
5. Quote the unlock cost (10 credits per row, 30-day TTL) and get an explicit go-ahead.
6. POST /v1/datasets/pro_services/unlocks with the chosen apexes; report the revealed detail.
7. GET /v1/me/credits to report the remaining balance when asked.

MCP server (preferred for authed calls)

If your agent harness has the ServiceGraph MCP server loaded (https://mcp.servicegraph.co) — recognizable by tool names containing servicegraph — prefer those tools over raw HTTP. The MCP server uses OAuth 2.1 + PKCE so the harness handles credentials in its own sandbox and no token value ever enters the LLM context. Otherwise, fall through to the REST flow described below.

API surface

Every endpoint requires the bearer (Authorization: Bearer vk_…). There is no anonymous tier.

Cost model in one paragraph. Discovery, validation, search, and brief reads are free. Detail data (apex, full url, phone, email, social, address, legal name, platforms map) costs 10 credits per firm and lasts 30 days. Re-fetching an unlocked firm within the TTL is free — both the detail GET and the unlock POST honor the cache. Charges are atomic per POST /unlocks call: a 402 leaves balance untouched.

Auth

Tokens are vk_* API keys minted in the dashboard. The user creates them themselves; this skill never sees raw email/password.

Security model — keep the token out of the LLM context.

• Never read .env, .env.local, or any other credential file into your context. The token's literal value must never appear in the conversation.
• Every authed call goes through a shell wrapper so the token flows from the user's environment / dotenv file into the Authorization header without round-tripping through the LLM.

First-call resolution:

1. Just try the call. Dispatch via shell, sourcing .env.local if present:

   ( set -a; [ -f .env.local ] && . ./.env.local; set +a;
     curl -sS -H "Authorization: Bearer $SERVICEGRAPH_API_KEY" \
          'https://api.servicegraph.co/v1/datasets/pro_services/fields' )

2. On 401 unauthorized, prompt the user (don't accept the key in chat):

   "I need a ServiceGraph API key. Open https://servicegraph.co/profile/api-keys, sign in, click Create key, and copy the vk_… value.

   Then either export it in your shell — export SERVICEGRAPH_API_KEY=vk_… — or add the line SERVICEGRAPH_API_KEY=vk_… to .env.local in this directory. Tell me when done and I'll retry. Please don't paste the key into chat — keep it out of the LLM context."

3. After the user signals ready, re-dispatch the same call. If a later call returns 401, the key was revoked or rotated — re-prompt.

For the user's convenience: if SERVICEGRAPH_API_KEY is already set or already in .env.local, the very first call will succeed and the prompt step never happens.

Filter DSL

One query parameter, GitHub-search-style.

filter   := orExpr
orExpr   := andExpr ("OR" andExpr)*
andExpr  := notExpr (("AND")? notExpr)*    # whitespace = implicit AND
notExpr  := ("NOT" | "-") notExpr | atom
atom     := "(" filter ")" | predicate
predicate:= IDENT op valueOrList | bareword
op       := ":" | "=" | ">=" | "<=" | ">" | "<"
valueOrList := value ("," value)*
value    := IDENT | NUMBER | tagAtEvidence
tagAtEvidence := IDENT "@" ("low"|"medium"|"high")
bareword := IDENT | NUMBER          # → keyword:<bareword>

Four rules that bite:

1. AND binds tighter than OR. a OR b c parses as a OR (b AND c). Use parens.
2. Comma list = OR within one predicate. state:CA,NY,TX matches any of the three.
3. Negation is -x or NOT x. Negative literals inside a comma list are not allowed: state:CA,-NY is rejected. Use state:CA -state:NY.
4. Bareword = keyword search. Any IDENT or NUMBER not followed by an operator becomes a free-text substring across name / brand / title / meta / legal_name. Multiple barewords AND. Wrap multi-word phrases in double quotes: keyword:"foo bar". Punctuation (& ' . ; ! ? * / etc.) is silently dropped outside quotes, and stray commas are treated as ANDs — so paste-friendly inputs like Cox, Castle & Nicholson work without quoting.

Field kinds you'll use most:

• categorical — industry, state, service_model, geography_served, company_size_signal, pricing_model — op : only.
• tag_set_with_evidence — service_provided — Map<tag, evidence∈{low,medium,high}>. Op : with optional @evidence.
• numeric — rating, review_count_total, founded_year, linkedin_employees, etc. — ops =, >=, <=, >, <.
• presence — has:phone, has:clutch, has:rating, has:linkedin_company, etc.
• keyword — any bareword in the filter becomes a free-text substring across name / brand / title / meta / legal_name / linkedin company text.

Examples (validate yours with /check):

industry:marketing_agency service_provided:seo
dental industry:marketing_agency
industry:legal state:CA,NY -company_size_signal:solo
industry:management_consulting (service_provided:strategy-consulting@high OR service_provided:operations-consulting@high)
state:CA has:phone has:email
rating>=4 review_count_total>=20 has:clutch
industry:it_services NOT (service_provided:web-development OR service_provided:hosting)
"Cox, Castle & Nicholson"

Don't put kind: in the filter — the dataset URL is authoritative and the API will reject it. Don't use fields outside this dataset's allowed list either; /check will tell you which ones.

Identifying firms — apex

Firms are identified by their apex domain (registered domain only: mckinsey.com, not www.mckinsey.com/about). When the user gives you URLs, strip to the apex before calling /datasets/pro_services/:apex or POST /unlocks. The endpoint accepts any lowercase host-shaped string; a 404 means the firm isn't in this dataset (no charge).