MCP auto-discovery — zero-config setup for Claude / Cursor / Windsurf

For: all
Tier: free+
Time: ~3 min

Why you'd do this

In 2026 the MCP ecosystem standardised on a .well-known discovery convention (SEP-2127): an AI client probes a single HTTP URL on a server's domain and learns everything it needs to connect — server identity, tool catalogue, transport types, auth flow. Same pattern OAuth uses (/.well-known/oauth-authorization-server). ComplianceLint implements this so customers can wire up Claude Desktop / Cursor / Windsurf / ChatGPT in one step instead of editing JSON config files.

Before you start

An MCP-compatible AI client installed (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, ChatGPT with MCP enabled, Goose, or VS Code with Copilot)
The client's MCP config UI (varies per client — Settings → MCP / Extensions / Tools)

Step 1

The discovery endpoint

ComplianceLint serves a static JSON document at:

https://compliancelint.dev/.well-known/mcp/server-card.json

It returns a structured description of the server:

Server identity: name (compliancelint), version, homepage, documentation URL
17 MCP tools categorized by purpose (discovery / auth / scan / guidance / evidence / meta)
Transport: STDIO (local subprocess via npx compliancelint)
Auth flow: optional cl_connect device-flow that links your scanner identity to a compliancelint.dev SaaS account
Scope: EU AI Act, EU regulatory geography
Capabilities: read-only static analysis (no file modify, no arbitrary code execution, no unprompted network requests)

Implementation follows SEP-2127, the official MCP server-discovery convention.

Step 2

The easy path — auto-discovery

If your AI client supports .well-known/mcp/server-card.json discovery (most major 2026 clients do):

Configure your client with compliancelint.dev as a server URL.
Client probes .well-known/mcp/server-card.json automatically.
Client prompts "Connect to ComplianceLint?" — confirm the connection.
Done — ComplianceLint MCP is available; all 17 tools auto-loaded into your tool palette.

No manual JSON edit. No client-restart-and-pray cycle.

Step 3

Verify the endpoint yourself

You can curl the live server card:

curl https://compliancelint.dev/.well-known/mcp/server-card.json | jq .

You should see name: "compliancelint", the current version, and a tools array with 17 entries (cl_scan, cl_action_plan, cl_explain, cl_connect, etc.).

If the JSON loads and the tools array is non-empty, the discovery endpoint is healthy and your client should be able to use it.

Step 4

Fallback — clients without auto-discovery

If your client doesn't support .well-known/mcp discovery yet (some early adopters / niche clients), run the manual setup:

npx compliancelint init

This writes the local MCP config and registers the scanner with your Claude Desktop / Cursor / Windsurf installation. See the Quick Start chapter for the full flow.

Step 5

Security — what's exposed, what isn't

The server card is public and crawlable by design — that's the point of the .well-known convention. Discovery wouldn't work if it weren't.

What IS exposed:

✅ Tool names (for client-side discovery)
✅ Auth scheme name (custom-device-flow) so clients know the flow
✅ Homepage / docs URLs (for human inspection)
✅ Transport types so clients pick the right one

What is NOT exposed:

❌ Tool input schemas with sensitive defaults
❌ Internal API endpoint paths beyond the public auth flow
❌ Any credential value (API keys, tokens, passwords)
❌ Per-user or per-account data
❌ Internal implementation details

The endpoint is rate-limited, served over HTTPS only, and returns X-Frame-Options: DENY + Content-Security-Policy: frame-ancestors 'none' headers as defense-in-depth.

Step 6

Coming soon: MCP Apps interactive widgets — Business tier

Post-launch we are upgrading select MCP tools to return interactive HTML widgets instead of text-only responses, per the MCP Apps specification (shipped January 2026 as the first official MCP extension under the Linux Foundation's Agentic AI Foundation).

Tier: Business (€199/month) only. Free / Starter / Pro users continue to get text-only responses from the same MCP tools, with a single-line upgrade hint at the end of each scan/explain output. The interactive widgets are a Business-tier feature alongside the Compliance All-in-One Pack and DoC / Technical Documentation PDFs.

What this will mean for Business users:

cl_scan results render as a sandboxed compliance dashboard — per-article status grid, click any row for source quote + evidence requirements + Mark NA button.
cl_action_plan becomes a drag-drop card stack — each obligation is a card; drag your file onto the card to upload evidence; embedded Recital cross-links and "see also Article X" clickthroughs.
cl_explain shows a 3-pane interactive view — source quote (verbatim from EUR-Lex) + decomposed atom tree + Recital references all clickable.

All widgets run in sandboxed iframes with restricted permissions, communicate with the host through inspectable JSON-RPC postMessage calls only, and have no backchannel — meeting SOC 2 Type II and GDPR audit requirements out of the box.

No date yet — tracked in the public roadmap. Phase A (the three highest-value tools above) is estimated at 3–4 days of focused work once the Phase 2 alignment work is closed and at least one major MCP host beyond Claude Desktop confirms stable MCP Apps support.

What can go wrong

Client says 'connection failed' even though the discovery URL responds 200 — Check the client's MCP version — older clients (pre-2025-06) may not understand SEP-2127 server-card schema. Upgrade the client or fall back to the manual npx compliancelint init path.
Client connects but no cl_* tools appear in the tool palette — The client found the server card but couldn't open an MCP session. Most common cause: the client's local environment lacks Node.js (needed to run npx compliancelint). Install Node 18+ and retry.
Curl returns a 404 or 5xx for .well-known/mcp/server-card.json — ComplianceLint.dev infrastructure issue — file a bug at github.com/ki-sum/compliancelint/issues with the curl response headers. Operationally, fall back to manual npx compliancelint init while we investigate.

Last updated: 2026-05-08

MCP auto-discovery — zero-config setup for Claude / Cursor / Windsurf

For: all
Tier: free+
Time: ~3 min

Why you'd do this

Before you start

An MCP-compatible AI client installed (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, ChatGPT with MCP enabled, Goose, or VS Code with Copilot)
The client's MCP config UI (varies per client — Settings → MCP / Extensions / Tools)

Step 1

The discovery endpoint

ComplianceLint serves a static JSON document at:

https://compliancelint.dev/.well-known/mcp/server-card.json

It returns a structured description of the server:

Server identity: name (compliancelint), version, homepage, documentation URL
17 MCP tools categorized by purpose (discovery / auth / scan / guidance / evidence / meta)
Transport: STDIO (local subprocess via npx compliancelint)
Auth flow: optional cl_connect device-flow that links your scanner identity to a compliancelint.dev SaaS account
Scope: EU AI Act, EU regulatory geography
Capabilities: read-only static analysis (no file modify, no arbitrary code execution, no unprompted network requests)

Implementation follows SEP-2127, the official MCP server-discovery convention.

Step 2

The easy path — auto-discovery

If your AI client supports .well-known/mcp/server-card.json discovery (most major 2026 clients do):

Configure your client with compliancelint.dev as a server URL.
Client probes .well-known/mcp/server-card.json automatically.
Client prompts "Connect to ComplianceLint?" — confirm the connection.
Done — ComplianceLint MCP is available; all 17 tools auto-loaded into your tool palette.

No manual JSON edit. No client-restart-and-pray cycle.

Step 3

Verify the endpoint yourself

You can curl the live server card:

curl https://compliancelint.dev/.well-known/mcp/server-card.json | jq .

You should see name: "compliancelint", the current version, and a tools array with 17 entries (cl_scan, cl_action_plan, cl_explain, cl_connect, etc.).

If the JSON loads and the tools array is non-empty, the discovery endpoint is healthy and your client should be able to use it.

Step 4

Fallback — clients without auto-discovery

If your client doesn't support .well-known/mcp discovery yet (some early adopters / niche clients), run the manual setup:

npx compliancelint init

This writes the local MCP config and registers the scanner with your Claude Desktop / Cursor / Windsurf installation. See the Quick Start chapter for the full flow.

Step 5

Security — what's exposed, what isn't

The server card is public and crawlable by design — that's the point of the .well-known convention. Discovery wouldn't work if it weren't.

What IS exposed:

✅ Tool names (for client-side discovery)
✅ Auth scheme name (custom-device-flow) so clients know the flow
✅ Homepage / docs URLs (for human inspection)
✅ Transport types so clients pick the right one

What is NOT exposed:

❌ Tool input schemas with sensitive defaults
❌ Internal API endpoint paths beyond the public auth flow
❌ Any credential value (API keys, tokens, passwords)
❌ Per-user or per-account data
❌ Internal implementation details

The endpoint is rate-limited, served over HTTPS only, and returns X-Frame-Options: DENY + Content-Security-Policy: frame-ancestors 'none' headers as defense-in-depth.

Step 6

Coming soon: MCP Apps interactive widgets — Business tier

What this will mean for Business users:

cl_scan results render as a sandboxed compliance dashboard — per-article status grid, click any row for source quote + evidence requirements + Mark NA button.
cl_action_plan becomes a drag-drop card stack — each obligation is a card; drag your file onto the card to upload evidence; embedded Recital cross-links and "see also Article X" clickthroughs.
cl_explain shows a 3-pane interactive view — source quote (verbatim from EUR-Lex) + decomposed atom tree + Recital references all clickable.

What can go wrong

Client says 'connection failed' even though the discovery URL responds 200 — Check the client's MCP version — older clients (pre-2025-06) may not understand SEP-2127 server-card schema. Upgrade the client or fall back to the manual npx compliancelint init path.
Client connects but no cl_* tools appear in the tool palette — The client found the server card but couldn't open an MCP session. Most common cause: the client's local environment lacks Node.js (needed to run npx compliancelint). Install Node 18+ and retry.
Curl returns a 404 or 5xx for .well-known/mcp/server-card.json — ComplianceLint.dev infrastructure issue — file a bug at github.com/ki-sum/compliancelint/issues with the curl response headers. Operationally, fall back to manual npx compliancelint init while we investigate.

Last updated: 2026-05-08

MCP auto-discovery — zero-config setup for Claude / Cursor / Windsurf

Why you'd do this

Before you start

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

What can go wrong

Related

MCP auto-discovery — zero-config setup for Claude / Cursor / Windsurf

Why you'd do this

Before you start

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

What can go wrong

Related