fix(plugin): wire .mcp.json remote MCP server for plugin installs (#60)

## Summary

- The repo already ships as a Claude Code plugin
(`.claude-plugin/plugin.json` + `marketplace.json`), but `.mcp.json` was
empty (`{ "mcpServers": {} }`), so installing the plugin registered
**no** MCP server — the skill loaded with no tools to call.
- Wire `.mcp.json` to register a `type: http` server at
`https://api.agentkey.app/v1/mcp`, injecting the API key via the
documented `${user_config.AGENTKEY_API_KEY}` interpolation (the manifest
already declares `userConfig.AGENTKEY_API_KEY`).
`${CLAUDE_PLUGIN_OPTION_*}` env vars only apply to stdio/subprocess
servers, not to an http server header.
- Correct the now-misleading `.mcp.json` guidance in
`.claude/CLAUDE.md`, and document the public marketplace install path
(`/plugin marketplace add chainbase-labs/agentkey`) in `README.md` +
`docs/README_zh.md`.

Scope: only `.mcp.json`, `.claude/CLAUDE.md`, `README.md`,
`docs/README_zh.md` (+28/-10). Version/release files untouched; the
`fix:` lets release-please cut 1.9.1 on merge.

## Test Plan

- [x] `claude plugin validate .` passes
- [x] Local end-to-end (isolated config): `claude plugin marketplace add
./` + `claude plugin install agentkey@agentkey --config
AGENTKEY_API_KEY=…` → `plugin:agentkey:agentkey … ✓ Connected`,
confirming `${user_config.*}` is interpolated into the auth header and
the server authenticates
- [x] `bats tests/` 10/10 pass
- [ ] Reviewer sanity-check of the 4-file diff

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude/CLAUDE.md

@@ -64,7 +64,7 @@ Releases are driven by [release-please](https://github.com/googleapis/release-pl
 - release-please automatically bumps `version` + `plugin.json` version + `CHANGELOG.md` from merged conventional-commit PRs; maintainers review + merge the generated Release PR rather than editing these files directly
 
 **Changes to `.mcp.json`:**
-- Ensure env var name matches `plugin.json` userConfig key via `CLAUDE_PLUGIN_OPTION_` prefix
+- 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`
 
 **Changes to install/uninstall docs:**
@@ -76,5 +76,5 @@ 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; API key flows from plugin userConfig → `Authorization: Bearer <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; the API key flows from plugin userConfig into the `Authorization: Bearer ${user_config.AGENTKEY_API_KEY}` header (no stdio binary is launched)
 - `README.md` / `docs/README_zh.md` are the public-facing docs; keep them in sync with any structural changes

.mcp.json

@@ -1,3 +1,11 @@
 {
-  "mcpServers": {}
-}
+  "mcpServers": {
+    "agentkey": {
+      "type": "http",
+      "url": "https://api.agentkey.app/v1/mcp",
+      "headers": {
+        "Authorization": "Bearer ${user_config.AGENTKEY_API_KEY}"
+      }
+    }
+  }
+}

README.md

@@ -346,14 +346,19 @@ 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** — add the repo as a local marketplace:
+**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**:
 
 ```bash
+# Public install
+claude plugin marketplace add chainbase-labs/agentkey
+claude plugin install agentkey@agentkey
+
+# …or from a local checkout, for development
 claude plugin marketplace add /absolute/path/to/agentkey
-claude plugin install agentkey
+claude plugin install agentkey@agentkey
 ```
 
-Reload with `claude plugin update agentkey` after edits. Use the skills-CLI path for day-to-day edits; the plugin path only for testing Claude Code plugin internals (e.g. MCP env-var wiring through `CLAUDE_PLUGIN_OPTION_*`).
+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.
 
 **Repo layout:**
 

docs/README_zh.md

@@ -346,14 +346,19 @@ 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 安装：
+**Claude Code 插件模式** —— 直接从 marketplace 安装。插件启用时会提示你填 AgentKey API Key 并自动接好 MCP server，**不需要再单独跑 `@agentkey/cli`**：
 
 ```bash
+# 公开安装
+claude plugin marketplace add chainbase-labs/agentkey
+claude plugin install agentkey@agentkey
+
+# …或从本地 checkout 安装，用于开发
 claude plugin marketplace add /absolute/path/to/agentkey
-claude plugin install agentkey
+claude plugin install agentkey@agentkey
 ```
 
-编辑文件后 `claude plugin update agentkey` 重新加载。日常 Skill 调整用 skills CLI 就够；只有在验证 Claude Code 插件内部机制（例如 `CLAUDE_PLUGIN_OPTION_*` 环境变量接线）时才走插件路径。
+启用时 Claude Code 会提示填 `AGENTKEY_API_KEY`（存进系统钥匙串），并通过 `${user_config.AGENTKEY_API_KEY}` 注入插件的 `.mcp.json`。改了本地 checkout 后用 `claude plugin update agentkey` 重新加载。日常 Skill 迭代仍是 skills CLI 最快；插件路径是给 Claude Code 用户的一步到位选项。
 
 **仓库结构：**