feat(plugin): OAuth-default MCP, health check, npm run check

- Default mcp.json: http + hosted URL only (no headers) for Cursor OAuth
- Add verify-mcp-health.mjs and npm run check (validate + health)
- CI: single check step; README/SUBMISSION/PR template aligned
- Docs: optional API-key fallback; rule + install script messaging
- Bump to 0.1.4

Made-with: Cursor

Author: jesseoue

.cursor-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
 	"name": "leadmagic",
 	"displayName": "LeadMagic",
-	"version": "0.1.3",
-	"description": "Official LeadMagic plugin for Cursor with hosted MCP: emails, mobile, LinkedIn-to-email, job changes, company research, competitors, technographics, and credits.",
+	"version": "0.1.4",
+	"description": "Official LeadMagic plugin for Cursor with hosted MCP (OAuth by default): emails, mobile, LinkedIn-to-email, job changes, company research, competitors, technographics, and credits.",
 	"author": {
 		"name": "LeadMagic",
 		"email": "plugins@leadmagic.io"

.github/pull_request_template.md

@@ -14,14 +14,14 @@
 
 ## Validation
 
-- [ ] Ran `npm run validate`
+- [ ] Ran `npm run validate` (or `npm run check` to include hosted health)
 - [ ] Checked that copy matches the current hosted MCP surface
 - [ ] Verified no secrets or hardcoded API keys were added
 
 ## Alignment Checklist
 
 - [ ] `mcp.json` still points to `https://mcp.leadmagic.io/mcp`
-- [ ] Auth still uses `x-leadmagic-key`
+- [ ] Default `mcp.json` stays OAuth-only (no headers); API-key fallback documented in README if needed
 - [ ] Repo copy does not imply MCP support for tools outside the current MCP surface
 - [ ] README and submission copy stay consistent
 

.github/workflows/validate-plugin.yml

@@ -17,6 +17,7 @@ on:
       - "rules/**"
       - "schemas/**"
       - "scripts/**"
+      - "CHANGELOG.md"
       - "skills/**"
 
 jobs:
@@ -38,25 +39,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Validate plugin package
-        run: npm run validate
-
-      - name: Check hosted MCP endpoint
-        run: |
-          node <<'EOF'
-          const fs = require('node:fs');
-          const data = JSON.parse(fs.readFileSync('mcp.json', 'utf8'));
-          const server = data.mcpServers?.leadmagic;
-
-          if (!server || server.type !== 'http' || server.url !== 'https://mcp.leadmagic.io/mcp') {
-            throw new Error('mcp.json must point to the hosted LeadMagic MCP endpoint with explicit HTTP transport');
-          }
-
-          if (!server.headers || server.headers['x-leadmagic-key'] !== '${LEADMAGIC_API_KEY}') {
-            throw new Error('mcp.json must use LEADMAGIC_API_KEY interpolation');
-          }
-          EOF
+      - name: Validate plugin and hosted health
+        run: npm run check
 
       - name: Check README references
         run: |
-          node -e "const fs=require('node:fs');const text=fs.readFileSync('README.md','utf8');for(const value of ['https://mcp.leadmagic.io/mcp','leadmagic://docs','LeadMagic MCP Tools']){if(!text.includes(value)){throw new Error('README.md is missing required reference: '+value)}}"
+          node -e "const fs=require('node:fs');const text=fs.readFileSync('README.md','utf8');for(const value of ['https://mcp.leadmagic.io/mcp','leadmagic://docs','LeadMagic MCP Tools','OAuth']){if(!text.includes(value)){throw new Error('README.md is missing required reference: '+value)}}"

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to the LeadMagic Cursor plugin package are documented here.
 
+## 0.1.4
+
+- **Auth:** Default `mcp.json` uses OAuth only (no headers); Cursor signs in with LeadMagic. README documents optional `x-leadmagic-key` + `${LEADMAGIC_API_KEY}` for API-key mode.
+- **CI:** `npm run check` runs validate plus `verify:health` against `https://mcp.leadmagic.io/health`; redundant `mcp.json` inline checks removed (covered by validate).
+
 ## 0.1.3
 
 - **MCP:** Hosted server at `https://mcp.leadmagic.io/mcp` — 10 tools, shared docs resource `leadmagic://docs`, prompts `account_research` and `contact_lookup`.

README.md

@@ -31,17 +31,31 @@ Use this plugin when you want Cursor to help with:
 
 ## Data and privacy
 
-MCP tool calls send the parameters you or the agent provide (for example emails, names, company names or domains, profile URLs) to LeadMagic's hosted service using your `LEADMAGIC_API_KEY`. See [Privacy](https://leadmagic.io/privacy) and [Terms](https://leadmagic.io/legal/terms). Support: [leadmagic.io/docs/support](https://leadmagic.io/docs/support).
+MCP tool calls send the parameters you or the agent provide (for example emails, names, company names or domains, profile URLs) to LeadMagic's hosted service. By default Cursor authenticates with LeadMagic using **OAuth** (browser sign-in) tied to your account. If you use the optional API-key setup, requests include your key from `LEADMAGIC_API_KEY`. See [Privacy](https://leadmagic.io/privacy) and [Terms](https://leadmagic.io/legal/terms). Support: [leadmagic.io/docs/support](https://leadmagic.io/docs/support).
 
 ## Hosted MCP Configuration
 
 The plugin points Cursor at LeadMagic's hosted MCP endpoint:
 
 - MCP endpoint: `https://mcp.leadmagic.io/mcp`
 - MCP transport: `http`
-- Auth header: `x-leadmagic-key`
-
-Users provide their API key through the `LEADMAGIC_API_KEY` environment variable. The plugin forwards that key to the hosted MCP server at runtime.
+- **Default auth:** OAuth sign-in in Cursor when you enable or first use the LeadMagic MCP server (no API key in `mcp.json`)
+
+**Optional API-key auth:** Advanced setups can add a static header so Cursor sends your key instead of OAuth. Merge or replace the server entry like this (environment variable must be visible to Cursor):
+
+```json
+{
+  "mcpServers": {
+    "leadmagic": {
+      "type": "http",
+      "url": "https://mcp.leadmagic.io/mcp",
+      "headers": {
+        "x-leadmagic-key": "${LEADMAGIC_API_KEY}"
+      }
+    }
+  }
+}
+```
 
 ## What The MCP Supports Today
 
@@ -76,13 +90,7 @@ For private team distribution in Cursor:
 
 ### Install locally for testing
 
-#### 1. Set your API key
-
-```bash
-export LEADMAGIC_API_KEY="your_api_key_here"
-```
-
-#### 2. Link the repository into Cursor
+#### 1. Link the repository into Cursor
 
 If you are using this repository locally:
 
@@ -95,7 +103,15 @@ This creates a symlink at `~/.cursor/plugins/local/leadmagic` pointing to this r
 
 Then reload Cursor with `Developer: Reload Window`.
 
-#### 3. Verify the connection
+#### 2. Sign in with LeadMagic (OAuth)
+
+When Cursor connects to the LeadMagic MCP server, complete the browser OAuth flow if prompted. You do not need `LEADMAGIC_API_KEY` for the default configuration.
+
+#### 3. Optional: use an API key instead of OAuth
+
+If you cannot use OAuth, set `LEADMAGIC_API_KEY` in an environment Cursor inherits and add the `headers` block shown under [Hosted MCP Configuration](#hosted-mcp-configuration).
+
+#### 4. Verify the connection
 
 Ask Cursor one of these:
 
@@ -105,13 +121,15 @@ Ask Cursor one of these:
 
 ## Local Development
 
-From the repository root, install dependencies and validate the package:
+From the repository root, install dependencies and run the full check:
 
 ```bash
 npm ci
-npm run validate
+npm run check
 ```
 
+If you cannot reach the network, use `npm run validate` instead of `check`.
+
 To link the plugin into Cursor locally:
 
 ```bash
@@ -126,21 +144,25 @@ npm run uninstall:local
 
 ## Troubleshooting
 
-### Cursor cannot see `LEADMAGIC_API_KEY`
+### OAuth or MCP sign-in fails
 
-On macOS, if Cursor was launched from the dock or Finder, it may not inherit your shell environment. If `LEADMAGIC_API_KEY` is set in your terminal but LeadMagic still fails inside Cursor, launch Cursor from the same shell session or reload it after exporting the variable in an environment Cursor can see.
+Retry the LeadMagic sign-in flow from Cursor's MCP settings. Confirm the server URL is `https://mcp.leadmagic.io/mcp` and that no stale custom `mcp.json` override is forcing invalid headers. If OAuth is blocked in your environment, switch to the API-key configuration in [Hosted MCP Configuration](#hosted-mcp-configuration).
 
-### Authentication fails
+### Cursor cannot see `LEADMAGIC_API_KEY` (API-key mode only)
+
+On macOS, if Cursor was launched from the dock or Finder, it may not inherit your shell environment. If you use the API-key header and `LEADMAGIC_API_KEY` is set in your terminal but LeadMagic still fails inside Cursor, launch Cursor from the same shell session or reload it after exporting the variable in an environment Cursor can see.
+
+### Authentication fails (API-key mode)
 
 Confirm that:
 
 - `LEADMAGIC_API_KEY` is set in the environment visible to Cursor
+- your merged MCP config includes `x-leadmagic-key` with `${LEADMAGIC_API_KEY}`
 - the plugin is using `https://mcp.leadmagic.io/mcp`
-- the request header is `x-leadmagic-key`
 
 ### Hosted MCP reachability
 
-`GET https://mcp.leadmagic.io/health` should return **200** when the service is up. Unauthenticated requests to `/mcp` may return **401** until a valid API key is sent— that is expected.
+`GET https://mcp.leadmagic.io/health` should return **200** when the service is up. Unauthenticated requests to `/mcp` may return **401** until OAuth completes or a valid API key is sent—that is expected.
 
 ### You need exact tool details
 
@@ -173,6 +195,7 @@ rules/leadmagic-usage.mdc
 skills/*/SKILL.md
 scripts/install-local-plugin.mjs
 scripts/validate-plugin.mjs
+scripts/verify-mcp-health.mjs
 README.md
 SUBMISSION.md
 CHANGELOG.md
@@ -181,13 +204,14 @@ CHANGELOG.md
 ## Validation
 
 ```bash
-npm run validate
+npm run check
 ```
 
+That runs `npm run validate` plus `npm run verify:health` (hosted `/health` smoke check—same idea as CI). Use `npm run validate` alone when you are offline.
+
 The validator checks this package against a vendored snapshot of Cursor's official `plugin.schema.json` and then applies LeadMagic-specific assertions for:
 
-- the hosted MCP endpoint
-- `LEADMAGIC_API_KEY` interpolation
+- the hosted MCP endpoint and OAuth-default `mcp.json` (no auth headers)
 - the canonical logo asset and submission logo URL
 - skills and rules metadata
 - repository and submission copy consistency

SUBMISSION.md

@@ -20,7 +20,7 @@ plugins@leadmagic.io
 https://raw.githubusercontent.com/LeadMagic/leadmagic-cursor-plugin/main/assets/logo.svg
 
 **Description**
-Official LeadMagic plugin for Cursor. Gives agents direct access to LeadMagic's hosted MCP surface for work email validation and discovery, mobile lookup, LinkedIn profile to work email, job-change detection, account research, competitor and technographics lists, people-by-role search, and credit balance—all using your API key with credit-aware usage.
+Official LeadMagic plugin for Cursor. Gives agents direct access to LeadMagic's hosted MCP surface for work email validation and discovery, mobile lookup, LinkedIn profile to work email, job-change detection, account research, competitor and technographics lists, people-by-role search, and credit balance—authenticated by default with OAuth in Cursor, with an optional API-key path for advanced setups.
 
 **GitHub repository**
 https://github.com/LeadMagic/leadmagic-cursor-plugin
@@ -37,12 +37,12 @@ Before submitting:
 3. Confirm the public logo URL resolves:
    `https://raw.githubusercontent.com/LeadMagic/leadmagic-cursor-plugin/main/assets/logo.svg`
 4. Run `npm ci`.
-5. Run `npm run validate`.
+5. Run `npm run check` (or `npm run validate` if you are offline).
 6. If you want to test the package in Cursor first, run `npm run install:local` and reload Cursor with `Developer: Reload Window`.
 
 ## Suggested reviewer note
 
-LeadMagic is an API-first B2B enrichment platform for AI agents and GTM engineers. This plugin packages our hosted MCP integration (10 tools, `leadmagic://docs`, two prompts) into a Cursor-native repo with focused skills, safe default guidance, and `LEADMAGIC_API_KEY` for auth. Tool calls are processed per LeadMagic privacy and terms at leadmagic.io.
+LeadMagic is an API-first B2B enrichment platform for AI agents and GTM engineers. This plugin packages our hosted MCP integration (10 tools, `leadmagic://docs`, two prompts) into a Cursor-native repo with focused skills, safe default guidance, and OAuth-first MCP auth (optional `LEADMAGIC_API_KEY` header for environments that need it). Tool calls are processed per LeadMagic privacy and terms at leadmagic.io.
 
 ## Short marketplace blurb alternatives
 
@@ -53,4 +53,4 @@ Official LeadMagic plugin for Cursor. Validate and find work emails, look up mob
 B2B enrichment for Cursor agents via LeadMagic's hosted MCP: emails, mobile, profiles, job changes, account intel, competitors, technographics, role search, and credit-aware usage.
 
 ### Option C
-Connect Cursor to LeadMagic for agent-native contact and account workflows backed by LeadMagic's hosted MCP and your own API key.
+Connect Cursor to LeadMagic for agent-native contact and account workflows backed by LeadMagic's hosted MCP and OAuth sign-in (API key optional).

mcp.json

@@ -1,11 +1,8 @@
 {
-  "mcpServers": {
-    "leadmagic": {
-      "type": "http",
-      "url": "https://mcp.leadmagic.io/mcp",
-      "headers": {
-        "x-leadmagic-key": "${LEADMAGIC_API_KEY}"
-      }
-    }
-  }
+	"mcpServers": {
+		"leadmagic": {
+			"type": "http",
+			"url": "https://mcp.leadmagic.io/mcp"
+		}
+	}
 }

package.json

@@ -1,12 +1,13 @@
 {
 	"name": "leadmagic-cursor-plugin",
 	"private": true,
-	"version": "0.1.3",
+	"version": "0.1.4",
 	"description": "Submission package for the LeadMagic Cursor plugin",
 	"license": "MIT",
 	"scripts": {
 		"validate": "node scripts/validate-plugin.mjs",
-		"validate:strict": "node scripts/validate-plugin.mjs",
+		"verify:health": "node scripts/verify-mcp-health.mjs",
+		"check": "npm run validate && npm run verify:health",
 		"install:local": "node scripts/install-local-plugin.mjs",
 		"uninstall:local": "node scripts/install-local-plugin.mjs --unlink"
 	},

rules/leadmagic-usage.mdc

@@ -24,4 +24,4 @@ When this plugin is available:
    - and any obvious next best step.
 6. For email validation, summarize only what appears in the tool output (including the stated result line). Do not speculate about “missing” deliverability details, catch-all behavior, or fields the response does not include.
 7. If parameter requirements, supported inputs, or pricing are unclear, consult the shared MCP docs resource `leadmagic://docs` before guessing.
-8. If the API key is missing or authentication fails, tell the user they need to set `LEADMAGIC_API_KEY`.
+8. If authentication fails, tell the user to finish LeadMagic sign-in for MCP in Cursor (OAuth), or use the API-key fallback in the plugin README (`LEADMAGIC_API_KEY` + `x-leadmagic-key` header) if OAuth is not available.

scripts/install-local-plugin.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import fs from "node:fs";
-import path from "node:path";
 import os from "node:os";
+import path from "node:path";
 
 const pluginRoot = process.cwd();
 const manifestPath = path.join(pluginRoot, ".cursor-plugin", "plugin.json");
@@ -48,7 +48,7 @@ try {
 	console.log(`Linked plugin to ${linkPath}`);
 	console.log("Next step: reload Cursor with 'Developer: Reload Window'.");
 	console.log(
-		"Important: make sure LEADMAGIC_API_KEY is available to the Cursor process before reloading.",
+		"After reload: complete LeadMagic OAuth when Cursor connects to MCP, or configure LEADMAGIC_API_KEY + headers per README if you use API-key mode.",
 	);
 } catch (error) {
 	console.error(error instanceof Error ? error.message : String(error));