From 32703dbb47e0ba7805c5030f97cd24d22f5930e8 Mon Sep 17 00:00:00 2001 From: Klappy Date: Wed, 15 Apr 2026 01:41:51 +0000 Subject: [PATCH] feat: add ?consumer= query param to getting started URLs and telemetry governance - Updated all oddkit URLs in getting-started article to include ?consumer=yourname - Added explanation of transparency leaderboard and what telemetry tracks - Updated telemetry-governance.md consumer resolution chain: query param is now priority 1 - Query param works on every platform (no custom header support needed) --- canon/constraints/telemetry-governance.md | 11 ++++++----- writings/getting-started-with-odd-and-oddkit.md | 12 +++++++----- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/canon/constraints/telemetry-governance.md b/canon/constraints/telemetry-governance.md index a3aba97e..97e19271 100644 --- a/canon/constraints/telemetry-governance.md +++ b/canon/constraints/telemetry-governance.md @@ -107,12 +107,13 @@ The principle: if it reveals what someone was *thinking* rather than what they w Consumer labels are resolved from whatever the request provides, in priority order: -1. `x-oddkit-client` header (explicit, highest priority) -2. MCP `initialize` → `clientInfo.name` (protocol-native) -3. `User-Agent` header (fallback) -4. `"unknown"` (default) +1. `?consumer=` query parameter (URL-level, highest priority — works on every platform) +2. `x-oddkit-client` header (explicit) +3. MCP `initialize` → `clientInfo.name` (protocol-native) +4. `User-Agent` header (fallback) +5. `"unknown"` (default) -No authentication is required. The hosted service is open. Unidentified consumers see a one-line footer on tool responses linking to this policy and explaining how to identify themselves. +No authentication is required. The hosted service is open. The query parameter is the recommended identification method because every MCP client lets users edit the URL, while not all platforms expose custom headers. Unidentified consumers see a one-line footer on tool responses linking to this policy and explaining how to identify themselves. ### Phase 2 — Track Who (OAuth for TruthKit) diff --git a/writings/getting-started-with-odd-and-oddkit.md b/writings/getting-started-with-odd-and-oddkit.md index 0c5b43d7..7e12266e 100644 --- a/writings/getting-started-with-odd-and-oddkit.md +++ b/writings/getting-started-with-odd-and-oddkit.md @@ -90,12 +90,14 @@ The difference isn't that the AI is smarter. It's that the AI is *focused*. oddkit is a remote MCP server. You don't install anything. You point your AI tool at a URL. Different tools call it different things — Claude calls them "connectors," ChatGPT calls them "apps," Lovable and Replit call them "MCP servers" — but the setup is always the same: give the tool a URL. +The base URL is `https://oddkit.klappy.dev/mcp`. You can optionally add `?consumer=yourname` to identify yourself on the public transparency leaderboard — oddkit tracks which tools are used and how often, but not what you search for or what documents contain. Adding your name helps the maintainer know the infrastructure is being used by real people. You can see the same data yourself by calling `telemetry_public`. Replace `yourname` with whatever you'd like to appear on the leaderboard — your name, a handle, a project name. Or leave it off entirely and stay anonymous. + ### Claude.ai Open Settings → Connectors → Add Custom Integration. Enter: - **Name:** `oddkit` -- **URL:** `https://oddkit.klappy.dev/mcp` +- **URL:** `https://oddkit.klappy.dev/mcp?consumer=yourname` That's it. Start a new conversation and oddkit's tools are available. @@ -103,7 +105,7 @@ That's it. Start a new conversation and oddkit's tools are available. Open Settings → Developer Mode → Create App. Add the MCP server URL: -`https://oddkit.klappy.dev/mcp` +`https://oddkit.klappy.dev/mcp?consumer=yourname` ### Claude Code / Cursor / Any MCP Client @@ -114,19 +116,19 @@ Add to your `.mcp.json` or MCP configuration: "mcpServers": { "oddkit": { "type": "http", - "url": "https://oddkit.klappy.dev/mcp" + "url": "https://oddkit.klappy.dev/mcp?consumer=yourname" } } } ``` -In Claude Code, you can also run: `claude mcp add --transport http oddkit https://oddkit.klappy.dev/mcp` +In Claude Code, you can also run: `claude mcp add --transport http oddkit https://oddkit.klappy.dev/mcp?consumer=yourname` ### Lovable / Replit / Gemini / ElevenLabs Voice Agents Same URL, same protocol. Any tool that supports MCP can connect to oddkit. Look for "MCP server," "custom integration," or "external tool" in your tool's settings and provide the URL: -`https://oddkit.klappy.dev/mcp` +`https://oddkit.klappy.dev/mcp?consumer=yourname` The setup varies by platform, but the URL is always the same.