MCP server

The MCP server is the acquisition lever. A developer running an MCP-aware IDE (Cursor, Claude Desktop, Windsurf) can reach four free tools without a key, then authenticate to unlock twelve gated tools — without leaving the editor. There are two ways to run it, sharing the identical 16-tool contract.

Two transports, one contract

• @cognilead/mcp-server — a stdio package the IDE spawns as a local child process (packages/mcp-server/src/index.ts). Free tools run fully locally with no network call.
• A hosted remote MCP endpoint at POST https://cognilead.ai/api/mcp — the MCP SDK's Streamable HTTP transport, run stateless (no session id, JSON responses, one Server instance per request) so no local install is needed at all.

app/api/mcp/tools.ts mirrors the stdio package's tool names, descriptions, and JSON Schemas inline (the two cannot share a module — the package is a separate, un-installed workspace excluded from the app's tsconfig), so keeping them in lockstep is a manual discipline, not an import.

The 4 free tools

• cognilead.draft_pitch — drafts a cold-outbound pitch (subject_line, email_body_markdown, technical_hook_verified, cited_source_url) from a company name, target product, and a public signal (a job post URL, GitHub repo, HN comment). Jurisdiction-aware model routing (CH/EU/UK/US/WORLD). No API key required.
• cognilead.score_signal — deterministic 0-100 fit score for a signal against a target product: keyword match × recency × source quality × URL-presence, with a breakdown and a recommended_action of pitch | enrich | skip. No LLM call, no API key required.
• cognilead.check_deliverability — looks up a domain's live SPF and DMARC TXT records over plain DNS and grades them (pass/warn/fail per record and overall), with specific findings such as "no 'all' mechanism", "+all disables SPF", or "no DMARC record — Gmail/Yahoo require it for bulk senders". Pure DNS lookup, no API key required.
• cognilead.health — proxies the public, keyless GET /api/v1/health. No API key required.

The 19 gated tools

Every gated tool requires Authorization: Bearer pk_live_… and dispatches by calling the app's OWN /api/v1/* endpoint with that same bearer token — the MCP layer adds no new capability beyond what the REST API already exposes to that exact key; it is a protocol wrapper, not a separate surface. Calling a gated tool with no key at all returns a curated { code: "mcp.unauthenticated", upgrade_url } error immediately, without a round-trip to the REST layer.

• cognilead.ingest_lead → POST /api/v1/leads. Runs the full intersect gate (§3).
• cognilead.run_campaign → POST /api/v1/campaigns/{id}/run, optionally scoped to lead_ids.
• cognilead.suppress → POST /api/v1/suppressions. Either email or domain must be provided.
• cognilead.create_topup_link → POST /api/v1/customers/{id}/topup. Starts a Stripe Checkout for a reselling tenant's end-customer prepaid balance.
• cognilead.list_leads, cognilead.list_sends, cognilead.list_suppressions — read-only, cursor-paginated (optional limit, cursor) proxies of the matching GET routes.
• cognilead.get_billing_usage → GET /api/v1/billing/usage. cognilead.get_subscription → GET /api/v1/billing/subscription.
• cognilead.list_webhooks → GET /api/v1/webhooks. cognilead.list_api_keys → GET /api/v1/keys (hashes and secrets stripped server-side — only id, prefix, label, and timestamps).
• cognilead.get_deliverability → GET /api/v1/deliverability.
• Sending domains: cognilead.search_domains → GET /api/v1/domains/search; cognilead.quote_domain → POST /api/v1/domains/quote; cognilead.buy_domain → POST /api/v1/domains (admin; needs confirm_charge_micro_usd equal to the quote's charge when the purchase is beyond the plan); cognilead.connect_domain → POST /api/v1/domains/connect (bring your own; returns the nameservers to set); cognilead.get_domain_status → GET /api/v1/domains/{id}; cognilead.list_domains → GET /api/v1/domains; cognilead.assess_domain → GET /api/v1/domains/assess.

// MCP tools/call request for a gated tool
{
  "method": "tools/call",
  "params": {
    "name": "cognilead.suppress",
    "arguments": { "email": "bounced@example.com", "reason": "bounce_hard" }
  }
}

// Unauthenticated gated-tool response
{
  "isError": true,
  "content": [{ "type": "text", "text": "{\"error\":{\"code\":\"mcp.unauthenticated\",\"message\":\"This tool requires a CogniLead API key. Get one at https://cognilead.ai (free tier available).\",\"upgrade_url\":\"https://cognilead.ai/signup?via=mcp\"}}" }]
}

Transport details

The hosted endpoint only accepts POST — GET and DELETE return 405, since it runs fully stateless (no session id, no server-initiated SSE stream to keep open or terminate). tools/list advertises all 16 tools regardless of whether a bearer key was presented; only tools/call enforces the gate at execution time. Server info reports name: "cognilead-mcp".