chainbase-labs · lxcong · Jul 17, 2026 · Jul 17, 2026
diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
@@ -0,0 +1,20 @@
+{
+  "name": "agentkey",
+  "interface": {
+    "displayName": "AgentKey"
+  },
+  "plugins": [
+    {
+      "name": "agentkey",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Data & Analytics"
+    }
+  ]
+}
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -1,18 +1,18 @@
 {
   "name": "agentkey",
-  "description": "Unified API for real-time external data: web search, social media, crypto/blockchain data, and web scraping",
+  "description": "One-stop live data marketplace for your agent: web search, web scraping, social media, finance, crypto, e-commerce, business data, weather/maps, and travel",
   "owner": {
     "name": "Chainbase Labs",
     "url": "https://agentkey.app"
   },
   "plugins": [
     {
       "name": "agentkey",
-      "description": "AgentKey — unified API for real-time external data: web search, social media (Twitter, Reddit, 小红书, Instagram, 知乎, TikTok, 抖音, B站, 微博, Threads, YouTube, LinkedIn), crypto/blockchain data, and web scraping",
+      "description": "AgentKey — one-stop live data marketplace for your agent: web search, web scraping, social media, finance, crypto, e-commerce, business data, weather/maps, and travel through a single MCP server. No API keys to manage, auto failover across providers, free to start.",
       "source": "./",
       "category": "data",
       "homepage": "https://github.com/chainbase-labs/agentkey",
-      "tags": ["agentkey", "web-search", "social-media", "crypto", "blockchain", "real-time-data", "scraping"]
+      "tags": ["agentkey", "web-search", "scraping", "social-media", "finance", "crypto", "blockchain", "e-commerce", "business-data", "weather", "maps", "travel", "real-time-data"]
     }
   ]
 }
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "agentkey",
   "version": "1.11.0",
-  "description": "AgentKey — unified API for real-time external data: web search, social media (Twitter, Reddit, 小红书, Instagram, 知乎, TikTok, 抖音, B站, 微博, Threads, YouTube, LinkedIn), crypto/blockchain data, and web scraping",
+  "description": "AgentKey — one-stop live data marketplace for your agent: web search, web scraping, social media, finance, crypto, e-commerce, business data, weather/maps, and travel through a single MCP server. No API keys to manage, auto failover across providers, free to start.",
   "author": {
     "name": "Chainbase Labs",
     "url": "https://agentkey.app"
@@ -11,11 +11,17 @@
   "keywords": [
     "agentkey",
     "web-search",
+    "scraping",
     "social-media",
+    "finance",
     "crypto",
     "blockchain",
-    "real-time-data",
-    "scraping"
+    "e-commerce",
+    "business-data",
+    "weather",
+    "maps",
+    "travel",
+    "real-time-data"
   ],
   "skills": "./skills/",
   "mcpServers": "./.mcp.json",

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -15,12 +15,18 @@ 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 (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.
 
+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.
+
 ## Directory Structure
 
 ```
 agentkey/
 ├── .claude-plugin/plugin.json   # Claude Code plugin manifest
-├── .mcp.json                    # Auto-registers AgentKey MCP when installed as a plugin
+├── .codex-plugin/
+│   ├── plugin.json              # Codex plugin manifest (skills + mcpServers + interface metadata)
+│   └── mcp.json                 # Codex MCP entry — http + oauth_resource (NOT the root .mcp.json)
+├── .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
 ├── skills/agentkey/
 │   ├── SKILL.md                 # Decision tree + routing rules (end-user facing)
 │   ├── scripts/                 # check-update helper
@@ -52,7 +58,7 @@ Releases are driven by [release-please](https://github.com/googleapis/release-pl
 
 ## Version & Release Rules
 
-- `skills/agentkey/version.txt`, `.claude-plugin/plugin.json` version, and `CHANGELOG.md` are managed by release-please based on Conventional Commits — never edit manually except via PR that intentionally amends them.
+- `skills/agentkey/version.txt`, `.claude-plugin/plugin.json` version, `.codex-plugin/plugin.json` version, and `CHANGELOG.md` are managed by release-please based on Conventional Commits — never edit manually except via PR that intentionally amends them.
 - `version.txt` lives inside `skills/agentkey/` (not at repo root) so it travels with the skill when the Skills CLI copies the subdirectory. `release-please-config.json` points at this path via `version-file`.
 - Tag format: `v` prefix (e.g. `v0.4.5`)
 - Plugin updates trigger on **GitHub Release** publication, not on plain commits
@@ -67,6 +73,11 @@ Releases are driven by [release-please](https://github.com/googleapis/release-pl
 - 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 `.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.
+- Do NOT set `oauth_resource`: rmcp already sends `resource` on its own, and Codex appends `oauth_resource` as a *second* `resource` query param without deduplication (`codex-rs/rmcp-client/src/perform_oauth_login.rs`). Clerk enforces RFC 6749 (no repeated params) and rejects the request with `invalid_request: The request includes the parameter 'resource' more than once`. The official Notion/Figma plugins get away with it only because their authorization servers tolerate duplicates.
+- Keep the endpoint URL in sync with the root `.mcp.json` — both must point at the same `/v1/mcp` endpoint.
+
 **Changes to install/uninstall docs:**
 - Update both `README.md` and `docs/README_zh.md` together — they mirror each other
 - The canonical install is always the two-command sequence (`npx skills add …` + `npx -y @agentkey/cli --auth-login`). Don't imply either command does both.

diff --git a/.codex-plugin/mcp.json b/.codex-plugin/mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agentkey": {
+      "type": "http",
+      "url": "https://api.agentkey.app/v1/mcp"
+    }
+  }
+}
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -0,0 +1,42 @@
+{
+  "name": "agentkey",
+  "version": "1.11.0",
+  "description": "AgentKey — one-stop live data marketplace for your agent: web search, web scraping, social media, finance, crypto, e-commerce, business data, weather/maps, and travel through a single MCP server. No API keys to manage, auto failover across providers, free to start.",
+  "author": {
+    "name": "Chainbase Labs",
+    "url": "https://agentkey.app"
+  },
+  "repository": "https://github.com/chainbase-labs/agentkey",
+  "license": "MIT",
+  "keywords": [
+    "agentkey",
+    "web-search",
+    "scraping",
+    "social-media",
+    "finance",
+    "crypto",
+    "blockchain",
+    "e-commerce",
+    "business-data",
+    "weather",
+    "maps",
+    "travel",
+    "real-time-data"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.codex-plugin/mcp.json",
+  "interface": {
+    "displayName": "AgentKey",
+    "shortDescription": "One-stop live data marketplace for your agent",
+    "longDescription": "AgentKey connects your agent to live external data through a single MCP server — web search, web scraping, social media, finance, crypto, e-commerce, business data, weather/maps, and travel — with no per-provider API integrations or key management. Providers are vetted and health-monitored, every call carries provenance, and auto failover keeps workflows running. Free to start.",
+    "developerName": "Chainbase Labs",
+    "category": "Data & Analytics",
+    "capabilities": ["Read"],
+    "websiteURL": "https://agentkey.app",
+    "defaultPrompt": [
+      "Search the web and social media for the latest news about a topic",
+      "Get the current price and on-chain activity for a crypto token",
+      "Scrape a URL and summarize its content"
+    ]
+  }
+}
diff --git a/.gitignore b/.gitignore
@@ -19,3 +19,4 @@ cli/.vitest/
 # Claude Code workflow artifacts (internal, not shipped publicly)
 docs/superpowers/
 RELEASE_NOTES.md
+.claude/worktrees/
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,93 @@
+# AGENTS.md
+
+This file provides guidance to coding agents (Codex, and any AGENTS.md-aware tool) when working with code in this repository. It mirrors `.claude/CLAUDE.md` — keep the two in sync.
+
+## What This Repo Is
+
+AgentKey Skill ships the agent-side half of AgentKey: a single skill that teaches agents how to call the AgentKey MCP tools correctly.
+
+AgentKey has **two pieces** and a full end-user install is two commands:
+
+1. `npx skills add chainbase-labs/agentkey` — installs **this** skill. It does NOT register the MCP server.
+2. `npx -y @agentkey/cli --auth-login` — runs the AgentKey CLI (`@agentkey/cli` from `../AgentKey-Server/cli`). It mints an API key via device-code login and writes a remote-HTTP MCP block (pointing at `https://api.agentkey.app/v1/mcp`) into agent configs (Claude Code, Codex, Cursor, and 13 more). The hosted MCP server itself lives at `/v1/mcp` on AgentKey-Server.
+
+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** (`.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 **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.
+
+## Directory Structure
+
+```
+agentkey/
+├── .claude-plugin/plugin.json   # Claude Code plugin manifest
+├── .codex-plugin/
+│   ├── plugin.json              # Codex plugin manifest (skills + mcpServers + interface metadata)
+│   └── mcp.json                 # Codex MCP entry — http + oauth_resource (NOT the root .mcp.json)
+├── .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
+├── skills/agentkey/
+│   ├── SKILL.md                 # Decision tree + routing rules (end-user facing)
+│   ├── scripts/                 # check-update helper
+│   └── version.txt              # Managed by release-please only — must live inside the skill so it survives `npx skills add`
+└── scripts/
+    └── uninstall.sh             # End-user cleanup helper
+```
+
+## Key Commands
+
+```bash
+# Test a local edit against every detected agent
+npx skills add .
+
+# Daily commit (does NOT trigger user updates)
+git add -A && git commit -m "..." && git push origin main
+
+# Publish a new release
+# Releases are cut automatically by release-please on merge to main.
+# To manually trigger: merge a conventional-commit PR; release-please will open
+# a Release PR; merge that to tag and create the GitHub Release.
+
+# Undo a bad release
+git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z
+gh release delete vX.Y.Z --repo chainbase-labs/agentkey --yes
+```
+
+Releases are driven by [release-please](https://github.com/googleapis/release-please): merged PRs with Conventional Commit messages (`feat:`, `fix:`, `feat!:`, etc.) update an open Release PR that bumps `skills/agentkey/version.txt`, both plugin manifest versions, and `CHANGELOG.md`. Merging the Release PR tags the release and creates the GitHub Release, which in turn triggers plugin updates for users.
+
+## Version & Release Rules
+
+- `skills/agentkey/version.txt`, `.claude-plugin/plugin.json` version, `.codex-plugin/plugin.json` version, and `CHANGELOG.md` are managed by release-please based on Conventional Commits — never edit manually except via PR that intentionally amends them.
+- `version.txt` lives inside `skills/agentkey/` (not at repo root) so it travels with the skill when the Skills CLI copies the subdirectory. `release-please-config.json` points at this path via `version-file`.
+- Tag format: `v` prefix (e.g. `v0.4.5`)
+- Plugin updates trigger on **GitHub Release** publication, not on plain commits
+- `npx skills update` pulls from the default branch, so main must always be shippable
+
+## Change Checklists
+
+**Changes to either `plugin.json`:**
+- release-please automatically bumps both 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`
+
+**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.
+- Do NOT set `oauth_resource`: rmcp already sends `resource` on its own, and Codex appends `oauth_resource` as a *second* `resource` query param without deduplication (`codex-rs/rmcp-client/src/perform_oauth_login.rs`). Clerk enforces RFC 6749 (no repeated params) and rejects the request with `invalid_request: The request includes the parameter 'resource' more than once`. The official Notion/Figma plugins get away with it only because their authorization servers tolerate duplicates.
+- Keep the endpoint URL in sync with the root `.mcp.json` — both must point at the same `/v1/mcp` endpoint.
+
+**Changes to install/uninstall docs:**
+- Update both `README.md` and `docs/README_zh.md` together — they mirror each other
+- The canonical install is always the two-command sequence (`npx skills add …` + `npx -y @agentkey/cli --auth-login`). Don't imply either command does both.
+- Do **not** re-add OpenClaw / per-agent installers without a new design — historical context is in git history (removed in chore/remove-archive-directory)
+
+## Architecture Constraints
+
+- 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)
+- `.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)
+- `README.md` / `docs/README_zh.md` are the public-facing docs; keep them in sync with any structural changes
diff --git a/README.md b/README.md
@@ -353,12 +353,27 @@ 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.
 
+**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**:
+
+```bash
+# Public install
+codex plugin marketplace add chainbase-labs/agentkey
+# then run /plugins inside Codex and install AgentKey,
+# or: codex plugin install agentkey@agentkey
+```
+
+The plugin manifest lives in `.codex-plugin/plugin.json`; it bundles the same skill plus a remote-HTTP MCP entry (`.codex-plugin/mcp.json`) that authenticates against `https://api.agentkey.app/v1/mcp` via MCP OAuth (RFC 9728 discovery). Sign in with your AgentKey account when Codex prompts you.
+
 **Repo layout:**
 
 ```
 agentkey/
 ├── .claude-plugin/plugin.json   # Claude Code plugin manifest
-├── .mcp.json                    # Used when installed as a plugin
+├── .codex-plugin/
+│   ├── plugin.json              # Codex plugin manifest
+│   └── mcp.json                 # Codex MCP entry (OAuth, no user_config)
+├── .agents/plugins/marketplace.json  # Codex marketplace (this repo is its own marketplace)
+├── .mcp.json                    # Used when installed as a Claude Code plugin
 ├── skills/agentkey/
 │   ├── SKILL.md                 # Decision tree + routing rules
 │   ├── scripts/                 # check-update helper