chainbase-labs · lxcong · Aug 13, 2026 · Aug 13, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -24,13 +24,5 @@
     "real-time-data"
   ],
   "skills": "./skills/",
-  "mcpServers": "./.mcp.json",
-  "userConfig": {
-    "AGENTKEY_API_KEY": {
-      "title": "AgentKey API Key",
-      "description": "Your AgentKey API key. Get one free at https://console.agentkey.app/",
-      "type": "string",
-      "sensitive": true
-    }
-  }
+  "mcpServers": "./.mcp.json"
 }
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -13,7 +13,7 @@ AgentKey has **two pieces** and a full end-user install is two commands:
 
 The skill is useless without the MCP server; the MCP server works without the skill but the agent won't know to prefer it over built-in web search. Keep this mental model when editing docs — do not let either command drift into claiming it does both.
 
-The same repo also works as a Claude Code plugin (via `.claude-plugin/plugin.json` + `.mcp.json`) for users on the plugin marketplace path; in that mode the plugin's `userConfig` + `.mcp.json` substitute for step 2.
+The same repo also works as a Claude Code plugin (via `.claude-plugin/plugin.json` + `.mcp.json`) for users on the plugin marketplace path; the remote HTTP entry has no static authentication header, so Claude Code follows the server's 401/RFC 9728 metadata into its native MCP OAuth flow. That OAuth sign-in substitutes for step 2.
 
 It additionally works as a **Codex plugin** (via `.codex-plugin/plugin.json` + `.codex-plugin/mcp.json`, distributed through `.agents/plugins/marketplace.json` — the repo is its own marketplace, added with `codex plugin marketplace add chainbase-labs/agentkey`). Codex plugins have no `userConfig`/header-interpolation mechanism, so auth uses MCP OAuth instead: the server's `/v1/mcp` endpoint advertises `WWW-Authenticate: Bearer resource_metadata=…` (RFC 9728) and supports dynamic client registration, so `.codex-plugin/mcp.json` needs only `type` + `url` — discovery does the rest. In that mode the OAuth sign-in substitutes for step 2.
 
@@ -38,7 +38,7 @@ agentkey/
 ├── .kimi-plugin/
 │   └── plugin.json              # Kimi Code manifest with inline HTTP MCP entry (OAuth)
 ├── .agents/plugins/marketplace.json  # Codex marketplace listing this repo as a local-source plugin
-├── .mcp.json                    # Auto-registers AgentKey MCP when installed as a Claude Code plugin
+├── .mcp.json                    # Claude MCP entry — HTTP + OAuth discovery, no static headers
 ├── gemini-extension.json        # Gemini CLI extension — Streamable HTTP + OAuth discovery
 ├── plugin.json                  # Antigravity desktop/CLI plugin marker
 ├── mcp_config.json              # Antigravity remote MCP entry — serverUrl + OAuth discovery
@@ -86,8 +86,9 @@ Releases are driven by [release-please](https://github.com/googleapis/release-pl
 - release-please automatically bumps all four manifest versions + `CHANGELOG.md` from merged conventional-commit PRs; maintainers review + merge the generated Release PR rather than editing these files directly
 
 **Changes to `.mcp.json`:**
-- The MCP server is `type: http` (remote endpoint, no subprocess), so inject the API key by interpolating the userConfig value as `${user_config.AGENTKEY_API_KEY}` in the `Authorization` header — the key name MUST match the `plugin.json` `userConfig` key. Do NOT use `${CLAUDE_PLUGIN_OPTION_<KEY>}`: those env vars are only exported to stdio/subprocess servers and hook/monitor commands, and are not interpolated into an http server's headers.
-- Only matters for the Claude Code plugin path; the Skills-CLI path writes MCP config through `npx @agentkey/cli --auth-login`
+- Keep the remote server as the minimal `type: http` + `url` entry. Do not add `headers`, `headersHelper`, `userConfig`, a static token, or an API-key placeholder.
+- Claude Code treats any configured `Authorization` header as explicit header authentication and does not fall back to OAuth when that header receives a 401. With no header, the server's 401 and RFC 9728 protected-resource metadata expose the native **Authenticate** action and `claude mcp login plugin:agentkey:agentkey` flow.
+- This applies only to the Claude Code plugin path; the Skills-CLI path still writes API-key MCP config through `npx @agentkey/cli --auth-login`.
 
 **Changes to `.codex-plugin/mcp.json`:**
 - Codex plugin MCP config does NOT support `${user_config.*}` interpolation — a literal `${…}` would be sent as the Authorization header. Auth is MCP OAuth via RFC 9728 discovery: the server's 401 advertises `resource_metadata`, and the rmcp client automatically appends `resource=<server url>` to the authorization request.
@@ -136,7 +137,7 @@ Releases are driven by [release-please](https://github.com/googleapis/release-pl
 
 - Setup mode in SKILL.md runs `! npx -y @agentkey/cli --auth-login` to authenticate via browser — same command as step 2 of the public install
 - `@agentkey/cli --auth-login` auto-writes MCP configs for 16 agents (canonical list lives in `AGENT_REGISTRY` in `../AgentKey-Server/cli/src/lib/mcp-clients.ts`): Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, OpenCode, Qwen Code, iFlow CLI, Kimi CLI, Kiro CLI, Windsurf, Warp, Amp, Crush, droid, openclaw. The `--only <ids>` flag (used by install.sh's `MCP_TARGETS` and install.ps1's `$McpTargets`) filters this list — its id values MUST match `npx skills add -a` ids, with `claude-desktop` as the one documented MCP-only exception. Goose / kode / kilo still need a manual JSON paste (see SKILL.md's "Fallback" section); when adding more agents server-side, keep `MCP_AUTO_AGENTS` in both install scripts and the cleanup list in both uninstall scripts in sync.
-- `.mcp.json` registers the remote-HTTP MCP endpoint (`https://api.agentkey.app/v1/mcp`) in Claude Code plugin mode; the API key flows from plugin userConfig into the `Authorization: Bearer ${user_config.AGENTKEY_API_KEY}` header (no stdio binary is launched)
+- `.mcp.json` registers the remote-HTTP MCP endpoint (`https://api.agentkey.app/v1/mcp`) in Claude Code plugin mode with no static header or `userConfig`; Claude Code performs native MCP OAuth discovery after the server's 401 response.
 - `.cursor-plugin/plugin.json` registers the same endpoint inline in Cursor plugin mode, authenticated through Cursor's native MCP OAuth flow
 - `.kimi-plugin/plugin.json` registers the same endpoint inline in Kimi Code plugin mode. After reloading, the user starts Kimi's native MCP OAuth flow with `/mcp-config login plugin-agentkey:agentkey`.
 - `gemini-extension.json` registers the same endpoint through `httpUrl` in Gemini CLI extension mode. Gemini discovers the existing `skills/agentkey/` tree; `oauth.enabled` starts native OAuth automatically and `/mcp auth agentkey` retries it manually.

diff --git a/.github/workflows/scripts-test.yml b/.github/workflows/scripts-test.yml
@@ -9,6 +9,8 @@ on:
       - 'gemini-extension.json'
       - 'plugin.json'
       - 'mcp_config.json'
+      - '.mcp.json'
+      - '.claude-plugin/plugin.json'
       - 'README.md'
       - 'docs/README_zh.md'
       - 'tests/**'
@@ -23,6 +25,8 @@ on:
       - 'gemini-extension.json'
       - 'plugin.json'
       - 'mcp_config.json'
+      - '.mcp.json'
+      - '.claude-plugin/plugin.json'
       - 'README.md'
       - 'docs/README_zh.md'
       - 'tests/**'

diff --git a/.mcp.json b/.mcp.json
@@ -2,10 +2,7 @@
   "mcpServers": {
     "agentkey": {
       "type": "http",
-      "url": "https://api.agentkey.app/v1/mcp",
-      "headers": {
-        "Authorization": "Bearer ${user_config.AGENTKEY_API_KEY}"
-      }
+      "url": "https://api.agentkey.app/v1/mcp"
     }
   }
 }
diff --git a/AGENTS.md b/AGENTS.md
@@ -15,7 +15,7 @@ The skill is useless without the MCP server; the MCP server works without the sk
 
 The same repo also works as:
 
-- a **Claude Code plugin** (`.claude-plugin/plugin.json` + root `.mcp.json`) — the plugin's `userConfig` injects the API key via `${user_config.AGENTKEY_API_KEY}`, substituting for step 2.
+- a **Claude Code plugin** (`.claude-plugin/plugin.json` + root `.mcp.json`) — the remote HTTP entry has no static authentication header, so Claude Code follows the server's 401/RFC 9728 metadata into its native MCP OAuth flow, substituting for step 2.
 - a **Codex plugin** (`.codex-plugin/plugin.json` + `.codex-plugin/mcp.json`, distributed through `.agents/plugins/marketplace.json`; the repo is its own marketplace: `codex plugin marketplace add chainbase-labs/agentkey`). Codex plugins have no `userConfig`/header-interpolation mechanism, so auth uses MCP OAuth via the server's RFC 9728 metadata discovery (`type` + `url` only in mcp.json), substituting for step 2.
 - a **Cursor plugin** (`.cursor-plugin/plugin.json`). The Cursor-native manifest bundles `skills/` and an inline remote-HTTP MCP entry. Cursor authenticates through the server's MCP OAuth discovery, substituting for step 2.
 - a **Kimi Code plugin** (`.kimi-plugin/plugin.json`). Kimi requires `mcpServers` to be an inline object in the manifest. The remote AgentKey endpoint uses Kimi's native MCP OAuth flow; after install Kimi shows the standard `/reload` hint, then the user signs in with `/mcp-config login plugin-agentkey:agentkey` when Kimi reports that OAuth is required.
@@ -35,7 +35,7 @@ agentkey/
 ├── .kimi-plugin/
 │   └── plugin.json              # Kimi Code manifest with inline HTTP MCP entry (OAuth)
 ├── .agents/plugins/marketplace.json  # Codex marketplace listing this repo as a local-source plugin
-├── .mcp.json                    # Auto-registers AgentKey MCP when installed as a Claude Code plugin
+├── .mcp.json                    # Claude MCP entry — HTTP + OAuth discovery, no static headers
 ├── gemini-extension.json        # Gemini CLI extension — Streamable HTTP + OAuth discovery
 ├── plugin.json                  # Antigravity desktop/CLI plugin marker
 ├── mcp_config.json              # Antigravity remote MCP entry — serverUrl + OAuth discovery
@@ -83,8 +83,9 @@ Releases are driven by [release-please](https://github.com/googleapis/release-pl
 - release-please automatically bumps all four manifest versions + `CHANGELOG.md` from merged conventional-commit PRs; maintainers review + merge the generated Release PR rather than editing these files directly
 
 **Changes to the root `.mcp.json` (Claude Code plugin path):**
-- The MCP server is `type: http` (remote endpoint, no subprocess), so inject the API key by interpolating the userConfig value as `${user_config.AGENTKEY_API_KEY}` in the `Authorization` header — the key name MUST match the `.claude-plugin/plugin.json` `userConfig` key. Do NOT use `${CLAUDE_PLUGIN_OPTION_<KEY>}`: those env vars are only exported to stdio/subprocess servers and hook/monitor commands, and are not interpolated into an http server's headers.
-- Only matters for the Claude Code plugin path; the Skills-CLI path writes MCP config through `npx @agentkey/cli --auth-login`
+- Keep the remote server as the minimal `type: http` + `url` entry. Do not add `headers`, `headersHelper`, `userConfig`, a static token, or an API-key placeholder.
+- Claude Code treats any configured `Authorization` header as explicit header authentication and does not fall back to OAuth when that header receives a 401. With no header, the server's 401 and RFC 9728 protected-resource metadata expose the native **Authenticate** action and `claude mcp login plugin:agentkey:agentkey` flow.
+- This applies only to the Claude Code plugin path; the Skills-CLI path still writes API-key MCP config through `npx @agentkey/cli --auth-login`.
 
 **Changes to `.codex-plugin/mcp.json` (Codex plugin path):**
 - Codex plugin MCP config does NOT support `${user_config.*}` interpolation — a literal `${…}` would be sent as the Authorization header. Auth is MCP OAuth via RFC 9728 discovery: the server's 401 advertises `resource_metadata`, and the rmcp client automatically appends `resource=<server url>` to the authorization request.
@@ -133,7 +134,7 @@ Releases are driven by [release-please](https://github.com/googleapis/release-pl
 
 - Setup mode in SKILL.md runs `! npx -y @agentkey/cli --auth-login` to authenticate via browser — same command as step 2 of the public install
 - `@agentkey/cli --auth-login` auto-writes MCP configs for 16 agents (canonical list lives in `AGENT_REGISTRY` in `../AgentKey-Server/cli/src/lib/mcp-clients.ts`): Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, OpenCode, Qwen Code, iFlow CLI, Kimi CLI, Kiro CLI, Windsurf, Warp, Amp, Crush, droid, openclaw. The `--only <ids>` flag (used by install.sh's `MCP_TARGETS` and install.ps1's `$McpTargets`) filters this list — its id values MUST match `npx skills add -a` ids, with `claude-desktop` as the one documented MCP-only exception. Goose / kode / kilo still need a manual JSON paste (see SKILL.md's "Fallback" section); when adding more agents server-side, keep `MCP_AUTO_AGENTS` in both install scripts and the cleanup list in both uninstall scripts in sync.
-- Root `.mcp.json` registers the remote-HTTP MCP endpoint (`https://api.agentkey.app/v1/mcp`) in Claude Code plugin mode; the API key flows from plugin userConfig into the `Authorization: Bearer ${user_config.AGENTKEY_API_KEY}` header (no stdio binary is launched)
+- Root `.mcp.json` registers the remote-HTTP MCP endpoint (`https://api.agentkey.app/v1/mcp`) in Claude Code plugin mode with no static header or `userConfig`; Claude Code performs native MCP OAuth discovery after the server's 401 response.
 - `.codex-plugin/mcp.json` registers the same endpoint in Codex plugin mode, authenticated via MCP OAuth (RFC 9728 discovery; no `oauth_resource` — see checklist above)
 - `.cursor-plugin/plugin.json` registers the same endpoint inline in Cursor plugin mode, authenticated through Cursor's native MCP OAuth flow
 - `.kimi-plugin/plugin.json` registers the same endpoint inline in Kimi Code plugin mode. After reloading, the user starts Kimi's native MCP OAuth flow with `/mcp-config login plugin-agentkey:agentkey`.

diff --git a/README.md b/README.md
@@ -339,7 +339,7 @@ npx -y @agentkey/cli --auth-login
 
 **Iterating on the MCP server itself?** The server lives at `AgentKey-Server/` (Go) and exposes the MCP endpoint at `/v1/mcp`. Run a local server (`make run`) and point your MCP config at `http://localhost:8081/v1/mcp` to test changes end-to-end.
 
-**Claude Code plugin mode** — install straight from the marketplace. The plugin prompts you for your AgentKey API key on enable and wires the MCP server for you, so there's **no second `@agentkey/cli` step**:
+**Claude Code plugin mode** — install straight from the marketplace. The plugin bundles a header-free remote HTTP entry and uses Claude Code's native MCP OAuth flow, so there is **no API key to paste and no second `@agentkey/cli` step**:
 
 ```bash
 # Public install
@@ -351,7 +351,7 @@ claude plugin marketplace add /absolute/path/to/agentkey
 claude plugin install agentkey@agentkey
 ```
 
-On enable, Claude Code prompts for `AGENTKEY_API_KEY` (stored in your OS keychain) and injects it into the plugin's `.mcp.json` via `${user_config.AGENTKEY_API_KEY}`. Reload a local checkout with `claude plugin update agentkey` after edits. Day-to-day skill iteration is still fastest via the skills-CLI path; the plugin path is the one-step option for Claude Code users.
+After installation, run `/reload-plugins`, open `/mcp`, select the AgentKey entry, and choose **Authenticate** to complete browser sign-in. From a terminal, `claude mcp login plugin:agentkey:agentkey` starts the same OAuth flow. The plugin's `.mcp.json` intentionally has no `Authorization` header: adding one makes Claude Code treat the server as header-authenticated and suppresses OAuth fallback after a 401. Reload a local checkout with `claude plugin update agentkey` after edits. Day-to-day Skill iteration is still fastest via the Skills CLI path; the plugin path is the OAuth-based option for Claude Code users.
 
 **Codex plugin mode** — install from the marketplace bundled in this repo. Auth is OAuth (browser sign-in on install), so there's **no API key to paste and no second `@agentkey/cli` step**:
 
@@ -437,7 +437,7 @@ agentkey/
 ├── .kimi-plugin/
 │   └── plugin.json              # Kimi manifest with inline MCP OAuth entry
 ├── .agents/plugins/marketplace.json  # Codex marketplace (this repo is its own marketplace)
-├── .mcp.json                    # Used when installed as a Claude Code plugin
+├── .mcp.json                    # Claude plugin MCP entry (OAuth discovery, no headers)
 ├── gemini-extension.json        # Gemini CLI extension manifest (MCP OAuth + skills)
 ├── plugin.json                  # Antigravity desktop/CLI plugin manifest
 ├── mcp_config.json              # Antigravity remote MCP entry (serverUrl + OAuth)

diff --git a/docs/README_zh.md b/docs/README_zh.md
@@ -339,7 +339,7 @@ npx -y @agentkey/cli --auth-login
 
 **想改 MCP Server 本身？** MCP server 在 `AgentKey-Server/`（Go），端点是 `/v1/mcp`。本地起服务（`make run`），把 MCP 配置指向 `http://localhost:8081/v1/mcp` 就能端到端验证。
 
-**Claude Code 插件模式** —— 直接从 marketplace 安装。插件启用时会提示你填 AgentKey API Key 并自动接好 MCP server，**不需要再单独跑 `@agentkey/cli`**：
+**Claude Code 插件模式** —— 直接从 marketplace 安装。插件内置不带 header 的远程 HTTP 配置，并使用 Claude Code 原生 MCP OAuth，**不用粘贴 API Key，也不需要再单独跑 `@agentkey/cli`**：
 
 ```bash
 # 公开安装
@@ -351,7 +351,7 @@ claude plugin marketplace add /absolute/path/to/agentkey
 claude plugin install agentkey@agentkey
 ```
 
-启用时 Claude Code 会提示填 `AGENTKEY_API_KEY`（存进系统钥匙串），并通过 `${user_config.AGENTKEY_API_KEY}` 注入插件的 `.mcp.json`。改了本地 checkout 后用 `claude plugin update agentkey` 重新加载。日常 Skill 迭代仍是 skills CLI 最快；插件路径是给 Claude Code 用户的一步到位选项。
+安装后运行 `/reload-plugins`，打开 `/mcp`，选择 AgentKey 并点击 **Authenticate**，然后在浏览器完成登录。也可以在终端运行 `claude mcp login plugin:agentkey:agentkey` 启动同一个 OAuth 流程。插件的 `.mcp.json` 会刻意保持无 `Authorization` header：一旦配置这个 header，Claude Code 就会把 server 判定为 header 认证，并在 401 后屏蔽 OAuth fallback。改了本地 checkout 后用 `claude plugin update agentkey` 重新加载。日常 Skill 迭代仍是 Skills CLI 最快；插件路径是 Claude Code 用户的 OAuth 安装方式。
 
 **Codex 插件模式** —— 从本仓库自带的 marketplace 安装。认证走 OAuth（安装时浏览器登录），**不用粘贴 API Key，也不需要再单独跑 `@agentkey/cli`**：
 
@@ -437,7 +437,7 @@ agentkey/
 ├── .kimi-plugin/
 │   └── plugin.json              # Kimi 清单，内联 MCP OAuth 配置
 ├── .agents/plugins/marketplace.json  # Codex marketplace（本仓库即自己的 marketplace）
-├── .mcp.json                    # 作为 Claude Code 插件安装时使用
+├── .mcp.json                    # Claude 插件 MCP 配置（OAuth 自动发现，无 headers）
 ├── gemini-extension.json        # Gemini CLI 扩展清单（MCP OAuth + skills）
 ├── plugin.json                  # Antigravity 桌面端/CLI 插件清单
 ├── mcp_config.json              # Antigravity 远程 MCP 配置（serverUrl + OAuth）