Agentkey: Instructions file for Codex

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 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.
• a Gemini CLI extension (root gemini-extension.json + skills/). Gemini requires the manifest at the extension root, discovers bundled agent skills automatically, and connects to AgentKey with httpUrl plus native MCP OAuth discovery. oauth.enabled requests the browser flow automatically; /mcp auth agentkey is the manual fallback. Either substitutes for step 2.
• an Antigravity 2.0 and Antigravity CLI plugin (root plugin.json + mcp_config.json + skills/). Both runtimes use the same package, require serverUrl for remote MCP, and authenticate through automatic OAuth discovery.
• a CLI-managed DeepSeek Harness integration. The installers detect ${DSH_HOME:-~/.dsh} / dsh, install the skill globally through the Skills CLI's universal target (never skills add -a dsh), and let @agentkey/cli --auth-login --only dsh maintain one marked @deepseek-ai/dsh-mcp-client entry in $DSH_HOME/cordis.patch.yml. DSH composes that home layer over current and future profiles; running processes watch it through HMR. DSH rc.7 has no MCP OAuth authProvider, so this path requires the CLI-written Bearer key. Tool policy may still hide tools.