Kingminos MCP Server

KingMinos by OutboundSync — MCP

Streamable HTTP MCP server that wraps the live KingMinos enrichment API at https://api.kingminos.com. One tool per bearer-authenticated resource route. Session and cookie routes under /v1/auth/* and /v1/account/* are permanently out of scope. This is not the OutboundSync product MCP and does not expose OutboundSync account, source, or sync tools.

LeadMagic, Wiza, Findymail, and AI Ark are the approved house-key vendors. ZoomInfo, BuiltWith, Prospeo, Apollo, Company URL Finder, People Data Labs, HG Insights, Brandfetch, Enrich-CRM, Lemlist, and Snov.io are BYOK via put_credentials. Websearch is house-only and cannot be stored. Snov.io is OAuth (clientId/clientSecret) and is a credential vendor only. Cognism, Lusha, Starbridge, Clay, Databar, QuickEnrich, GetLeads, and BlitzAPI are API-key credential vendors only — no routing hop yet. The server never embeds vendor keys and never logs the tenant Bearer or credential bodies.

Say SFDC, never SF.

BYOK provider rollout: four-repo checklist and narrative live in docs/byok-provider-playbook.md; Cursor agents can load .cursor/skills/byok-provider-rollout/SKILL.md.

Production host

Admin tools (admin token only)

abuse_report, partner_report, partner_payout, feedback_report and partner_admin wrap /v1/admin/abuse/daily, /v1/admin/partners/analytics, /v1/admin/partners/payouts, /v1/admin/feedback and /v1/admin/partners (list, create partner + code, add/deactivate code). They are registered only when the MCP bearer is a KingMinos admin token (kmadm_…, hashed in the API's D1, minted by Harris with scripts/mint-admin-token.ts in kingminos-application). Any other bearer never sees them in tools/list; an admin bearer sees only these admin tools. The API re-checks the token on every call. They are not OpenAPI resource operations, so check:surfaces ignores them.

Production is Cloudflare Worker kingminos-mcp-prod on the existing OutboundSync Cloudflare account. Janus deploys it with Wrangler:

npx wrangler deploy

Production MCP URL: https://mcp.kingminos.com/mcp. The custom domain mcp.kingminos.com is attached in Cloudflare and tracked in wrangler.jsonc (routes with custom_domain: true) so Janus deploys keep the hostname. workers_dev is false, so the Worker is not published on *.workers.dev (custom domain only).

This Worker must not bind D1 outboundsync-router, R2 outboundsync-router-raw, or Worker outboundsync-router. API base stays https://api.kingminos.com.

Fly is not the production host. fly.example.toml / Dockerfile are a local Node fallback sample only — not a production config.

Run it locally

Requires Node 22.

npm install
npm run build
npm start

The process listens on HOST (default 127.0.0.1) and PORT (default 8080) and serves the same paths as the Worker.

Dev (tsx, no build):

npm run dev

Contract check against the vendored inventory (inventory/openapi-surfaces.json). Deterministic; no live network. Default PR CI uses this pin — it does not fetch production OpenAPI.

npm run check:surfaces
npm run check:providers

check:surfaces compares advertised MCP tools to operations[]. check:providers compares the Zod ProviderName / CredentialProvider enums to the pinned providers[] / credentialProviders[]. A new BYOK id such as prospeo, companyurlfinder, peopledatalabs, hginsights, brandfetch, enrichcrm, or lemlist fails CI until both Zod enums and the pin list it — that is how routing.only: ["prospeo"] and put_credentials({ provider: "prospeo" }) stay accepted.

/v1/auth/* and /v1/account/* are intentionally not MCP tools (cookie/session app surfaces). They are denied by nonToolPathPrefixes plus the reviewed excludedOperationIds catalog. Do not implement those ~24 operations as tools.

Live OpenAPI drift check (scheduled CI / workflow_dispatch, or local). Surfaces compare only bearer resource operations after the deny-list — account/auth on the live spec is not a failure. Provider live check is one-way: it fails only when production lists a provider Zod does not have. Production lagging the pin (missing prospeo) does not fail. Override the spec URL with KINGMINOS_OPENAPI_JSON_URL (default https://api.kingminos.com/openapi.json):

npm run check:surfaces:live
npm run check:providers:live

Refresh the pin from live OpenAPI (network). Unions provider enums and newly seen auth/account operationIds; never drops pinned providers. Credential-only vendors (snovio, cognism, lusha, starbridge, clay, databar, quickenrich, getleads, blitzapi — no routing hop) are skipped from providers[]; the hand-written capabilityProviders pin is preserved. Review the diff before committing:

npm run inventory:refresh

Application CI can point at its own inventory with KINGMINOS_OPENAPI_INVENTORY=/path/to/openapi-surfaces.json. This repo does not vendor KingMinos application source.

Smoke (starts an ephemeral listener and lists tools; uses the file inventory, not the live spec):

npm test
npm run smoke

Worker bundle check (no Cloudflare auth required):

npm run check:worker

Full local suite:

npm run ci

That is exactly what the required OpenAPI tool contract check runs on PRs and main (branches must be up to date; protection applies to admins, so no direct pushes to main). npm install also installs git hooks (simple-git-hooks): pre-commit runs biome check --write on staged files, pre-push runs typecheck + tests. The nightly live drift job opens a Live OpenAPI drift issue instead of blocking PRs. CI map for all kingminos-* repos: kingminos-application/docs/ci.md.

Releases (CalVer)

After CI succeeds on a push to main, the CalVer Release workflow tags that commit (YYYY.MM.DD.N, UTC) and opens a GitHub release with generated notes. It does not push commits to main (Workers Builds deploys kingminos-mcp-prod on every main push).

The runtime version (/health, service card, MCP serverInfo) comes from export const VERSION in src/config.ts (kept in sync with package.json; see src/fetch.test.ts). Bump both in a normal PR when you want production to advertise a newer version than the last tag. Optional local helper: npm run release:apply stamps those files to the next CalVer tag without creating a release.

Preview the next tag and notes: npm run release:preview.

Tenant Bearer

The KingMinos tenant Bearer is sent by the client as Authorization: Bearer <token>. The server never mints, embeds, or logs that value.

Worker mode never reads KINGMINOS_API_KEY from process.env or from Worker bindings. A missing Authorization header is always 401 on the Worker.

A local Node process may fall back to KINGMINOS_API_KEY only when all of these are true:

• the process is bound to loopback (127.0.0.1, localhost, or ::1)
• KINGMINOS_MCP_ALLOW_ENV_BEARER=1

Production Workers do not store this secret. The value is never printed here.

POST /mcp rejects a present Origin that is not allowlisted. Clients that send no Origin keep working (typical MCP clients hitting https://mcp.kingminos.com/mcp). Local default hosts are localhost, 127.0.0.1, and [::1]; production also admits mcp.kingminos.com.

Optional:

• KINGMINOS_API_URL — API base (default https://api.kingminos.com). Path prefixes on this URL are preserved.
• HOST — local Node listen address (default 127.0.0.1)
• PORT — local Node listen port (default 8080)
• KINGMINOS_MCP_ALLOWED_HOSTS — comma-separated Host allowlist for /mcp (Node default = loopback; Worker empty = allow all)
• KINGMINOS_MCP_ALLOWED_ORIGINS — extra Origin hostnames for /mcp
• KINGMINOS_MCP_PUBLIC_URL — advertised MCP URL on the server card (Worker default https://mcp.kingminos.com/mcp). The card never uses the client Host header.
• KINGMINOS_MCP_ALLOW_ENV_BEARER — set to 1 to opt in to the local loopback env-bearer fallback
• KINGMINOS_OPENAPI_INVENTORY — path to the file inventory used by check:surfaces, check:providers, and PR CI
• KINGMINOS_OPENAPI_JSON_URL — override URL for check:surfaces:live / check:providers:live / inventory:refresh

Copy .env.example for local names only. Do not commit a filled .env. Do not put secrets in Wrangler vars or files.

Cursor

Add to ~/.cursor/mcp.json (or project .cursor/mcp.json).

Local:

{
  "mcpServers": {
    "kingminos": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer ${env:KINGMINOS_API_KEY}"
      }
    }
  }
}

Hosted (production):

{
  "mcpServers": {
    "kingminos": {
      "url": "https://mcp.kingminos.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:KINGMINOS_API_KEY}"
      }
    }
  }
}

Cursor GUI sessions do not inherit shell .env files. Export KINGMINOS_API_KEY into the GUI environment so ${env:KINGMINOS_API_KEY} resolves.

Tools

Every tool is the snake_case operationId of one bearer-authenticated KingMinos resource route. /health, OpenAPI docs, and session/cookie /v1/auth/* + /v1/account/* routes are not tools.

Capability POSTs spend credits and write runs even though they do not write SFDC. Confirm put_credentials, delete_credentials, delete_subject, and webhook mutations (create_webhook, patch_webhook, delete_webhook, rotate_webhook_secret, test_webhook, replay_webhook_delivery) with the user. CI fails if this list drifts from the OpenAPI inventory.

Sentry

src/worker.ts is wrapped with @sentry/cloudflare withSentry (project outboundsync/kingminos-mcp). Errors only (tracesSampleRate: 0); the SDK is off unless the SENTRY_DSN secret is set (wrangler secret put, piped). No request bodies, tool arguments, auth headers, cookies, query strings, emails, LinkedIn URLs or km*_ (incl. kmadm_, kmwhsec_) / osr_ tokens leave the Worker (src/sentry.ts). Release: --var SENTRY_RELEASE:$(git rev-parse HEAD) at deploy, else the Worker version id.