Connecting an agent

Two ready-made ways in. Both talk to the same API, so pick whichever suits the tool you use — or use both.

Claude Code plugin — the quickest route

One install, and it brings the MCP server, the skill and the account commands with it.

/plugin marketplace add hc-sousa/bluesky-copilot
/plugin install kunpilot@kunpilot

Then add an account with the key you created above:

/kunpilot:add-account kunp_a1b2c3d4_...

Restart Claude Code (or /reload-plugins) and ask for what you want: "what's my best time to post?", "draft three posts about the launch", "what did I post that did best last month?"

Keeping it current

• The MCP server updates itself. Every config here says kunpilot-mcp@latest, and you pick up a new version on the next start.
• The plugin does not. Third-party marketplaces do not auto-update, so run /plugin marketplace update kunpilot (or turn auto-update on under /plugin → Marketplaces).

Write the @latest out in full. Dropping it — npx -y followed by just the package name — looks equivalent and is not. npx keys its cache by the exact spec string, and for anything that parses as a version range — a bare name is the range *, and @0.3 is the range 0.3 — it reuses the cached copy without ever asking the registry. A bare invocation has served a binary three versions old, from before stored accounts existed, and reported a missing API key while the credential file sat there full. Only a tag (@latest) or an exact version (@0.4.0) re-resolves.

The server logs its version to stderr on startup and warns when it is behind what npm reports, so if something looks wrong you can check what is actually running:

npx -y kunpilot-mcp@latest --version

Several accounts

Add each one, then choose the default:

/kunpilot:add-account kunp_second_key
/kunpilot:accounts
/kunpilot:use alice.bsky.social

Keys are stored once in ~/.kunpilot/credentials.json (mode 0600), so they never go into a config file. Within a session you can just ask Claude to switch accounts; every result names the account it acted on, so which one you are touching stays visible.

If you want a single account and no credentials file, leave it out and set the plugin's API key option instead — Claude Code keeps that in your OS keychain.

The skill on its own

Without the plugin, copy the skill in and set one key:

git clone https://github.com/hc-sousa/bluesky-copilot.git
mkdir -p ~/.claude/skills
cp -r bluesky-copilot/agent/plugin/skills/bluesky-copilot ~/.claude/skills/
export KUNPILOT_API_KEY=kunp_a1b2c3d4_...

MCP server

Works with Claude Desktop, Claude Code, and any other MCP client. Nothing to clone and nothing to build -- npx fetches it.

{
  "mcpServers": {
    "bsky-alice": {
      "command": "npx",
      "args": ["-y", "kunpilot-mcp@latest"],
      "env": {"KUNPILOT_API_KEY": "kunp_a1b2c3d4_..."}
    }
  }
}

Confirm a key works before wiring it up. This prints the handle it drives, with no model involved:

KUNPILOT_API_KEY=kunp_... npx -y kunpilot-mcp@latest --check

Several accounts

Add one server entry per account, named after the handle:

{
  "mcpServers": {
    "bsky-alice":   {"command": "npx", "args": ["-y", "kunpilot-mcp@latest"],
                     "env": {"KUNPILOT_API_KEY": "kunp_a1b2c3d4_..."}},
    "bsky-brandco": {"command": "npx", "args": ["-y", "kunpilot-mcp@latest"],
                     "env": {"KUNPILOT_API_KEY": "kunp_e5f6g7h8_..."}}
  }
}

That is deliberate rather than one server holding several keys. Each server knows exactly one account, so its tools cannot be pointed at the wrong one; a leaked config exposes one account rather than all of them; and you can give one account a read-only key while another gets write access. MCP clients show the server name alongside each tool, so the model can see which account it is touching.

On startup the server calls GET /me/ and puts the handle into every tool description, so a model with two servers connected can tell them apart.

Anything else

Point it at /llms.txt. It is the whole API in one plain-text file, written so an agent can work from it without any other documentation.

What agents will not do

• Publish without asking. Publishing requires an explicit confirmation flag, so a well-behaved agent checks with you first.
• Spend your AI credit by default. Both clients prefer the free prompt routes and run the prompt themselves, only using the paid routes when you ask for them by name.
• Create or revoke keys. Key management is browser-only, on purpose. A key that could mint another key would be a way for a leaked key to entrench itself. add-account only stores a key you already created; it cannot make one.
• Act on an account without saying so. Every tool result names the account it touched, and publishing additionally requires the agent to name the account back as confirmation.