Agent quickstart

MCP server for B2B intelligence.

The B2B intelligence layer built for agents. Pay per call, not per seat.

ElevList exposes B2B company intelligence as MCP-callable primitives — your agent reads firmographics, tech stack, hiring signals, and ICP fit through one config block. One install, every MCP-aware runtime.

§2 · 60-second install

You install ElevList the same way you install any other MCP server: one block in your client’s config file, one environment variable, one restart of the client.

You will need an API key. Claim one in 60 seconds with a curl one-liner — see §5.1.

2.1 — Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Add the elevlist server under mcpServers:

{
  "mcpServers": {
    "elevlist": {
      "url": "https://mcp.elevlist.com/m3",
      "auth": {
        "type": "bearer",
        "token": "${ELEVLIST_API_KEY}"
      }
    }
  }
}

Restart Claude Desktop. The elevlist tool group appears in the tool palette.

2.2 — Cursor

Edit .cursor/mcp.json in your project root, or use Cursor’s MCP settings panel:

{
  "mcpServers": {
    "elevlist": {
      "url": "https://mcp.elevlist.com/m3",
      "auth": {
        "type": "bearer",
        "token": "${ELEVLIST_API_KEY}"
      }
    }
  }
}

Restart Cursor.

2.3 — Windsurf

Open Windsurf’s MCP settings panel (Settings → MCP → Add server) and paste the same JSON block as Cursor.

2.4 — Any MCP-compliant client

The mcpServers block above is spec-compliant for any MCP HTTP-transport client (including reference clients on modelcontextprotocol.io). Paste the same JSON, point your client at https://mcp.elevlist.com/m3, set the bearer token from ELEVLIST_API_KEY.

ChatGPT custom-GPT bridge. Bridge-specific install instructions ship with the bridge.

2.5 — Set the env var (all clients)

export ELEVLIST_API_KEY="sk_live_..."        # paste the key returned by §5.1

Add the line to your shell init (.zshrc, .bashrc, fish equivalent) so the variable persists.

API key shape. sk_live_<32-char base62>, ~190 bits of entropy. The first 4 characters after sk_live_ form an audit prefix shown in dashboards and logs (e.g. sk_live_4f1c…); the remaining 28 characters are the secret. Never commit the full key to a repo.

§3 · Your first call (Sales Jarvis walkthrough)

This is what a new MCP install looks like in practice. We use the Sales Jarvis use case from the agent-era product strategy — find a company, check tech stack, decide if it’s worth a sales touch.

Step 1 — Ask your agent a real question

In Claude Desktop / Cursor / Windsurf, after the install:

“Look up vercel.com on ElevList. What’s their tech stack and are they hiring engineers right now?”

Step 2 — Watch the agent call the MCP tools

The agent calls one tool for the company payload, then a second for active hiring signals. Both calls return structured JSON.

Illustrative tool names: elevlist.company, elevlist.signals. Canonical MCP tool names will be published when the MCP tool registry locks. The HTTP endpoints in §4 are the contract today.

Step 3 — Read the structured response

The company-intelligence tool returns the wedge payload:

{
  "domain": "vercel.com",
  "name": "Vercel",
  "firmographics": { "headcount_range": "...", "hq_country": "..." },
  "tech_stack": [ /* current stack, normalized */ ],
  "icp_fit": { "score": 0.0, "drivers": [] },
  "_meta": {
    "confidence": 0.0,
    "freshness_seconds": 3600,
    "last_updated": "...",
    "proof_count": 0,
    "data_completeness_score": 0.0,
    "schema_version": "v1"
  }
}

Illustrative wedge shape — the canonical wedge schema is published with the API reference.

Every endpoint returns a top-level _meta block with confidence, freshness_seconds, last_updated, proof_count, data_completeness_score, schema_version. The agent uses these to decide whether to trust, defer, compare, or re-query. freshness_seconds is the age of the underlying evidence in seconds; last_updated is the wall-clock ISO-8601 write time.

The next section maps each natural-language ask above to the underlying HTTP endpoint and MCP tool group.

§4 · The six primitives

Each primitive is one MCP tool call, one HTTP endpoint, one example query, one response shape. Use them composed (the agent decides) or directly (you call them yourself).

4.1 — Company intelligence

“Pull the full intelligence wedge for vercel.com.”

GET /v1/companies/vercel.com
Authorization: Bearer $ELEVLIST_API_KEY

Returns the assembled company wedge payload (firmographics + tech stack + active signals + ICP fit + _meta). One call replaces several lookups across separate primitives.

4.2 — Facts

“Give me the raw normalized facts on vercel.com — I want to filter myself.”

GET /v1/companies/vercel.com/facts
Authorization: Bearer $ELEVLIST_API_KEY

Returns a paginated array of normalized facts. Lower-level than the wedge: the agent inspects individual normalized facts instead of the assembled wedge payload.

4.3 — Signals

“Show me only what changed at vercel.com in the last 90 days.”

GET /v1/companies/vercel.com/signals
Authorization: Bearer $ELEVLIST_API_KEY

Returns active signals only by default (hiring events, tech adoption, news, funding). Pass query parameters to widen the time window or include resolved signals.

4.4 — Relationships

“What’s vercel.com’s local graph — competitors, partners, customers I can reach through them?”

GET /v1/companies/vercel.com/relationships
Authorization: Bearer $ELEVLIST_API_KEY

Returns the local graph neighborhood (not the global graph). Pagination is cursor-based.

4.5 — Reverse ICP

“Find me 20 B2B SaaS companies in the US that switched CRMs in the last 6 months and are hiring engineers.”

POST /v1/reverse-icp
Authorization: Bearer $ELEVLIST_API_KEY
Content-Type: application/json

{
  "constraints": {
    "industry": "B2B SaaS",
    "geo": "US",
    "signals": ["crm_switch_last_180d", "hiring_engineering"]
  },
  "limit": 20
}

Returns ranked companies with score drivers and _meta. The expensive primitive — rate-limited and metered.

What’s “reverse ICP”? The inverse query: given the company’s profile, who should sell to it? It’s the same engine as ICP-fit scoring, run from the other direction.

4.6 — Category companies

“List companies in the developer-platforms category, ranked by relevance.”

GET /v1/categories/developer-platforms/companies
Authorization: Bearer $ELEVLIST_API_KEY

Lighter payload than companies/{domain} — designed for browsing or seeding a list. Pagination cursor-based.

§5 · Auth + key claim

One key. Four surfaces. Tiered rate limits.

5.1 — Claim a key (60 seconds)

POST /v1/keys/claim HTTP/1.1
Host: api.elevlist.com
Content-Type: application/json

{ "label": "agent-laptop", "owner_email": "you@yourdomain.com" }

Response:

{
  "id": "key_01HX...",
  "key": "sk_live_4f1c...<28 more chars>",
  "key_prefix": "sk_live_4f1c",
  "tier": "free"
}

The key value is shown once. Save it to your password manager, then set ELEVLIST_API_KEY in your shell and restart your MCP client:

export ELEVLIST_API_KEY="sk_live_4f1c..."

A web UI for this flow ships at elevlist.com/keys at launch (2026-06-02). Until then, the curl above is the canonical claim.

The exact request shape for self-serve claim is finalising under ELEAAA-688 ahead of launch (2026-06-02); the curl above will be re-baselined before docs-live (2026-05-29).

Rotate or revoke

• Lost your key? elevlist auth rotate <key_id> from the CLI. No plaintext recovery — the database stores SHA-256 only.
• Compromised? elevlist auth revoke <key_id> --immediate. Worst-case 60-second propagation.

§6 · Pricing

Free tier

• 60 requests/minute, 1,000 requests/day. Locked across all four surfaces (HTTP API, MCP HTTP, MCP stdio, CLI).
• All endpoints accessible at the free tier. No feature-gating between free and paid — same data shape, same _meta.
• Hard 429 + Retry-After header at the cap, JSON body points to the upgrade URL.

Paid (per-call, prepaid credits)

No seats. No annual contract. You pay only for the calls your agent makes.

Credit pack denominations, refund terms, and anti-abuse rules are documented on the pricing page.

§7 · Reliability and latency

ElevList commits to a published SLO across the agent-tier API. Targets below are the contract you can engineer your agent against.

Reliability

99.9% monthly availability across the agent-tier API. 43.2 minutes downtime budget per month.

Latency targets (P95)

Cold crawls hit external page fetchers. First-time-seen domains should be treated as async paths in your agent; subsequent calls are cached.

§8 · The 402 flow — what your agent sees on the paywall

ElevList’s paid tier is wired through HTTP 402 Payment Required, not session-bound subscriptions. Your agent talks to the gateway in three steps.

Step 1 — initial paid call without credits

GET /v1/companies/vercel.com HTTP/1.1
Authorization: Bearer $ELEVLIST_API_KEY

→ HTTP/1.1 402 Payment Required
X-ElevList-Price: 0.01                  # USD per call, up to 4 decimal places
X-ElevList-Price-Currency: USD
X-ElevList-Payment-URL: https://elevlist.com/credits/checkout?...
Content-Type: application/json

{ "error": "payment_required", "free_fallback_available": true,
  "upgrade": { "price_usd": 0.01, "payment_url": "..." } }

The agent reads X-ElevList-Price and X-ElevList-Payment-URL immediately. No human in the loop required.

Step 2 — credit-backed retry

After the operator has prepaid credits (one-time setup at the payment URL above), the agent retries:

GET /v1/companies/vercel.com HTTP/1.1
Authorization: Bearer $ELEVLIST_API_KEY
X-ElevList-Credits-Token: ct_...

→ HTTP/1.1 200 OK
{ "domain": "vercel.com", ... }

Token validation, credit debit, and full-response release are atomic from the caller’s perspective.

Step 3 — no credits, free fallback

If the agent has no valid credits token and the endpoint has a public-equivalent response, the gateway returns the free version + instructions for purchasing credits. The 402 path preserves the same endpoint and response family — your agent does NOT have to switch routes.

Refilling credits. Buy a pack at the X-ElevList-Payment-URL returned by any 402. Credit pack denominations, refund terms, and anti-abuse rules are documented on the pricing page.

§9 · Troubleshooting