AgentKey Integration: Web, Social, and On-Chain Data Access for AI Agents

{ "TITLE": "AgentKey Reference Document", "BODY": "## Overview\n\nAgentKey provides AI agents with unified access to external data sources through a single subscription. Instead of managing multiple API keys and separate bills for each data provider, you install AgentKey once and your agent can fetch web search results, social media content, cryptocurrency data, financial information, e-commerce listings, business intelligence, and GitHub repository data through one interface.\n\nThe product is in early access, so some rough edges are expected. The team plans to add Maps and Weather capabilities in the future.\n\n## When to Use AgentKey\n\nUse AgentKey when your agent needs to perform any of these tasks:\n\n- Fetch real-time web search results or scrape web pages\n- Access social media content from Twitter, Instagram, LinkedIn, YouTube, Bilibili, Reddit, or Douyin/TikTok\n- Retrieve on-chain or cryptocurrency data such as token prices, market data, and wallet activity\n- Obtain financial data including stock and foreign exchange quotes, company financials, and earnings reports\n- Access e-commerce data like product listings, prices, and reviews\n- Gather business or competitive intelligence about companies, funding rounds, investors, and people\n- Read GitHub repositories, including README files and issues\n- Avoid managing multiple API keys and subscriptions for different data sources\n\n## Capabilities\n\nAgentKey routes requests to underlying providers automatically, and the set of providers grows over time. Your agent can call find_tools to see currently available capabilities.\n\n### Web Search and Scraping\n\nSearch across search engines, news sources, and real-time discovery. Extract clean article text, structured data, and metadata from any URL.\n\n### On-Chain and Cryptocurrency Data\n\nAccess token prices, market data, on-chain activity, and project metadata.\n\n### Social and Content Platforms\n\nRetrieve public posts, videos, and discussions from major platforms including Twitter, Instagram, LinkedIn, YouTube, Bilibili, Reddit, and Douyin/TikTok.\n\n### Financial Data\n\nObtain stock and foreign exchange quotes, technical indicators, company financials, and earnings reports.\n\n### E-Commerce Data\n\nAccess product listings, prices, reviews, and best-seller data across major marketplaces.\n\n### Business Intelligence\n\nGather company, funding, investor, and people data for market research.\n\n### GitHub Repository Access\n\nRead README files and issues from public repositories.\n\n## Prerequisites\n\nBefore installing AgentKey, ensure you have:\n\n- An AI agent installed on the machine (Claude Code, Codex, Gemini CLI, Cursor CLI, Manus, or similar)\n- An internet connection for installation and MCP server communication\n- For macOS or Linux: a bash shell\n- For Windows: PowerShell\n- For manual installation: Node.js and npx available (required for skills commands)\n- For Claude Code plugin: Claude Code installed\n- For Codex plugin: Codex installed\n- For local development: Go (for MCP server) and git\n- An AgentKey subscription (sign up at console.agentkey.app)\n\n## Installation\n\n### Standard Install (macOS or Linux)\n\nRun this command in your terminal:\n\n\ncurl -fsSL https://agentkey.app/install.sh | bash\n\n\nA browser tab opens for login. Complete the authentication process. After that, restart your AI agent. Test the installation with a query like "What has Musk been tweeting about lately?"\n\n### Standard Install (Windows PowerShell)\n\nRun this command in PowerShell:\n\n\nirm https://agentkey.app/install.ps1 | iex\n\n\nA browser tab opens for login. Complete the authentication process. Restart your AI agent and test with a query like "What has Musk been tweeting about lately?"\n\n### Manual Two-Step Install\n\nIf the standard installer cannot reach your machine, use the manual approach:\n\n1. Install the skill: npx skills add chainbase-labs/agentkey\n2. Authenticate and register the MCP server: npx -y @agentkey/cli --auth-login\n\n### Install as Claude Code Plugin (Marketplace)\n\nRun these commands:\n\n\nclaude plugin marketplace add chainbase-labs/agentkey\nclaude plugin install agentkey@agentkey\n\n\nWhen you enable the plugin, Claude Code prompts for AGENTKEY_API_KEY, which is stored in the OS keychain. No second @agentkey/cli step is needed.\n\n### Install as Codex Plugin (Marketplace)\n\nRun this command:\n\n\ncodex plugin marketplace add chainbase-labs/agentkey\n\n\nThen run /plugins inside Codex and install AgentKey, or run:\n\n\ncodex plugin install agentkey@agentkey\n\n\nAuthentication uses OAuth with browser sign-in on install. No API key to paste and no second @agentkey/cli step is needed.\n\n### Install from Local Checkout (Development)\n\nClone the repository and install the working tree:\n\n\ngit clone https://github.com/chainbase-labs/agentkey.git && cd agentkey\nnpx skills add .\n\n\nRegister the MCP server if not already done:\n\n\nnpx -y @agentkey/cli --auth-login\n\n\n### Advanced Install Options\n\nThese flags modify the behavior of the standard installer script. For bash, use the -- prefix; for PowerShell, use the - prefix.\n\n| Bash Flag | PowerShell Flag | Description |\n|---|---|---|\n| --yes | -Yes | Non-interactive install to every detected agent without prompts |\n| --list-agents | -ListAgents | List which agents the installer would auto-select, then exit |\n| --only | -Only | Comma-separated list of agent names to install into (overrides auto-detection) |\n| --all-agents | -AllAgents | Skip agent detection; install for every agent the skills CLI finds |\n| --skip-mcp | -SkipMcp | Install only the skill, skip MCP authentication step |\n| --skip-skill | -SkipSkill | Install only the MCP authentication, skip skill installation |\n| --no-telemetry | Not available | Opt out of anonymous usage telemetry during installation |\n\nExample for bash:\n\n\ncurl -fsSL https://agentkey.app/install.sh | bash -s -- --yes\ncurl -fsSL https://agentkey.app/install.sh | bash -s -- --list-agents\ncurl -fsSL https://agentkey.app/install.sh | bash -s -- --only claude-code,cursor\ncurl -fsSL https://agentkey.app/install.sh | bash -s -- --all-agents\ncurl -fsSL https://agentkey.app/install.sh | bash -s -- --skip-mcp\ncurl -fsSL https://agentkey.app/install.sh | bash -s -- --skip-skill\n\n\nExample for PowerShell:\n\n\nirm https://agentkey.app/install.ps1 | iex -Yes\nirm https://agentkey.app/install.ps1 | iex -ListAgents\nirm https://agentkey.app/install.ps1 | iex -Only claude-code,cursor\nirm https://agentkey.app/install.ps1 | iex -AllAgents\nirm https://agentkey.app/install.ps1 | iex -SkipMcp\nirm https://agentkey.app/install.ps1 | iex -SkipSkill\n\n\n### Manual MCP Setup for Unsupported Agents\n\nAuto-configuration covers Claude Code, Claude Desktop, and Cursor. For other agents such as Codex, OpenCode, Gemini CLI, Hermes, Manus, or Linux Claude Desktop, the skill installs automatically but the MCP snippet must be pasted manually.\n\nPaste this MCP snippet into the agent's configuration file (the path varies per agent):\n\n\n{\"mcpServers\":{\"agentkey\":{\"type\":\"http\",\"url\":\"https://api.agentkey.app/v1/mcp\",\"headers\":{\"Authorization\":\"Bearer ak_...\"}}}}\n\n\nRestart the agent. The skill's first-run activation will also walk through this process.\n\n### Headless, SSH, or Docker Authentication\n\nWhen running in a headless environment, SSH session, or Docker container, the authentication step tries to open a browser and prints a URL. Copy that URL to any device with a browser to finish authentication.\n\nAlternatively, for manual key entry, run:\n\n\nnpx -y @agentkey/cli --setup\n\n\nThis opens an interactive wizard.\n\n## Update\n\n### Update AgentKey (Claude Code)\n\nOn the first call of a session, the skill runs a silent version check. If a new release is available, the user is prompted to upgrade. With consent, it runs:\n\n\nnpx skills update -g agentkey\n\n\n### Update AgentKey (Claude Desktop, Cursor, Other Clients Without Inline Bash Tool)\n\nStarting with version 1.4.0, the MCP server publishes the latest skill version via the agentkey_skill_meta tool. The agent calls it once per session and compares it against its own version. If a newer version exists, the agent prompts the user to upgrade with the exact command for that client.\n\n### One-Time Bootstrap for Pre-1.4.0 Skill on Claude Desktop\n\nFor skills older than version 1.4.0 on Claude Desktop, the metadata tool exists but the skill rule does not know how to read it. Use this one-time bootstrap procedure:\n\n1. Set DESKTOP_BASE to the session folder under skills-plugin (usually ~/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin).\n2. Download the latest repository: curl -fsSL https://github.com/chainbase-labs/agentkey/archive/refs/heads/main.tar.gz -o /tmp/agentkey.tar.gz\n3. Extract: tar -xzf /tmp/agentkey.tar.gz -C /tmp\n4. Copy skill files: find \"$DESKTOP_BASE\" -type d -path \"*/skills/agentkey\" 2>/dev/null | while read dst; do cp -R /tmp/agentkey-main/skills/agentkey/. \"$dst\"/; done\n5. Fully quit and restart Claude Desktop.\n\n### Force Manual Update (Any Client)\n\nTo refresh skill content:\n\n\nnpx skills update agentkey\n\n\nTo pin a specific version:\n\n\nnpx skills add chainbase-labs/agentkey@v1.0.0\n\n\n## Uninstall\n\n### Standard Uninstall (macOS or Linux)\n\nRun this command:\n\n\ncurl -fsSL https://agentkey.app/uninstall.sh | bash\n\n\nOptionally pass --keep-marketplace to retain the Claude Code plugin marketplace entry.\n\n### Standard Uninstall (Windows PowerShell)\n\nRun this command:\n\n\nirm https://agentkey.app/uninstall.ps1 | iex\n\n\nOptionally pass -KeepMarketplace to retain the Claude Code plugin marketplace entry.\n\n### Manual Two-Step Uninstall\n\n1. Remove the skill from every agent: npx skills remove chainbase-labs/agentkey\n2. Delete the agentkey entry under mcpServers in each MCP client configuration file. The file locations are:\n - Claude Code: ~/.claude.json\n - Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\n - Claude Desktop Windows: %APPDATA%\\Claude\\claude_desktop_config.json\n - Cursor: ~/.cursor/mcp.json\n\nThe manual two-step uninstall does not clean npm or npx caches, legacy shell rc entries, CLAUDE.md sections, or MCP stdio logs.\n\n## Telemetry\n\nAgentKey collects only anonymous usage telemetry: which agent is installed, the skill version, and upgrade outcomes. It never collects queries or responses.\n\nOpt out persistently: touch ~/.config/agentkey/telemetry-disabled\n\nOpt out for a single session: Set the environment variable AGENTKEY_TELEMETRY=0 before running your command.\n\nOpt out at install time: curl -fsSL https://agentkey.app/install.sh | bash -s -- --no-telemetry\n\nRe-enable telemetry: Delete the file ~/.config/agentkey/telemetry-disabled.\n\n## Status Check\n\nInside your agent, run:\n\n\n/agentkey status\n\n\nThis command diagnoses the MCP configuration, version, and connectivity.\n\n## Constraints and Caveats\n\n- AgentKey has no access to local files, credentials, or agent conversations.\n- The MCP server is hosted at https://api.agentkey.app/v1/mcp and is always up to date. No local upgrade is needed for the server.\n- The @agentkey/cli package only writes remote-HTTP MCP configuration. It never needs to be re-run unless you are rotating your API key.\n- The npx skills update command writes to ~/.agents/skills/agentkey and ~/.claude/skills/agentkey for Claude Code.\n- Claude Desktop reads from its own sandbox path, which is not touched by npx skills update. For Claude Desktop, use the one-time bootstrap command for updates on pre-1.4.0 skills.\n- Re-run npx -y @agentkey/cli --auth-login only when rotating your API key.\n- The one-command uninstaller removes the skill from every agent, strips the MCP entry and API key from all configurations, and clears caches and logs.\n- The manual two-step uninstall does not clean npm or npx caches, legacy shell rc entries, CLAUDE.md sections, or MCP stdio logs.\n- Auto-configuration covers Claude Code, Claude Desktop, and Cursor. For other agents, the skill installs automatically but the MCP snippet must be pasted manually.\n- In headless, SSH, or Docker environments, the authentication step prints a URL. Copy it to another device or use the interactive wizard with npx -y @agentkey/cli --setup.\n- For Claude Code plugin mode, no second @agentkey/cli step is needed. The API key is prompted on enable.\n- For Codex plugin mode, OAuth authentication happens on install. No API key to paste and no second @agentkey/cli step is needed.\n- When iterating on the skill, use npx skills add . with a local path or file:// URL. Re-run after each edit to skills/agentkey/SKILL.md.\n- For MCP server iteration, run the local server with make run (default port 8081) and point the MCP configuration to http://localhost:8081/v1/mcp to test changes.\n- The release process is for maintainers only. Releases are cut automatically by release-please. Merge a pull request with a feat: or fix: title to open a Release PR. The Release PR bumps skills/agentkey/version.txt, plugin.json, and CHANGELOG.md. Merging the Release PR creates a tag, a GitHub Release, and uploads the agentkey.skill asset.\n\n## Failure Modes\n\n- Without AgentKey, the agent cannot access social media platforms such as Twitter or Instagram. It will be blocked or prompted to log in.\n- Without AgentKey, the agent cannot scrape web pages. It returns raw HTML or 403 errors.\n- Without AgentKey, the agent cannot access on-chain data. You must navigate block explorers manually.\n- Without AgentKey, the agent cannot read YouTube or Bilibili videos. No subtitles are available.\n- Without AgentKey, the agent cannot access LinkedIn profiles. It encounters 403 access issues.\n- Without AgentKey, the agent cannot scrape trending lists from Douyin or TikTok.\n- Without AgentKey, the agent cannot read GitHub repositories. You must click through manually.\n- If credits are exhausted, usage is billed pay-as-you-go as overage. You can upgrade your plan at console.agentkey.app.\n- For pre-1.4.0 skills on Claude Desktop, the metadata tool exists but the skill rule does not know how to read it. Use the one-time bootstrap procedure.\n- The npx skills update command does not update Claude Desktop because it reads from a sandbox. Use the Desktop bootstrap command.\n- If the installer cannot reach the machine, use the manual two-step install.\n- If no usable display is available (headless, SSH, Docker), copy the printed URL to another device or use the interactive wizard.\n\n## Example Use Cases\n\nThese examples illustrate what you can ask your agent to do after installing AgentKey:\n\n- "What has Musk been saying on Twitter lately?" – AgentKey pulls relevant tweets and summarizes them.\n- "What do people think of this product on Instagram?" – AgentKey scrapes real posts and organizes them by sentiment.\n- "What does this YouTube or Bilibili video cover?" – AgentKey reads the video transcript and extracts key points.\n- "Find Reddit threads about this pain point." – AgentKey finds relevant threads and extracts solutions.\n- "Check this competitor's or candidate's LinkedIn." – AgentKey opens the page and summarizes key information.\n- "What's trending on Douyin or TikTok right now?" – AgentKey pulls trending topics and tags.\n- "What does this webpage say?" – AgentKey extracts content and explains it clearly.\n- "What does this GitHub repo do?" – AgentKey reads the README and Issues, then provides a one-line summary.\n- "What has this wallet or fund been buying lately?" – AgentKey summarizes recent transactions and positions.\n\n## Local Development\n\n### Iterate on the MCP Server\n\nThe server lives in the AgentKey-Server directory and is written in Go. The endpoint is /v1/mcp. Run the local server with:\n\n\nmake run\n\n\nThe default port is 8081. Point your MCP configuration to http://localhost:8081/v1/mcp to test changes.\n\n### Iterate on the Skill\n\nUse npx skills add . with a local path or a file:// URL. Re-run this command after each edit to skills/agentkey/SKILL.md.\n\n## Release Process (Maintainers Only)\n\nReleases are cut automatically by release-please. To trigger a release:\n\n1. Merge a pull request with a feat: or fix: title to open a Release PR.\n2. The Release PR bumps skills/agentkey/version.txt, plugin.json, and CHANGELOG.md.\n3. Merging the Release PR creates a tag, a GitHub Release, and uploads the agentkey.skill asset." }