← Back to BotVault

MCP-based Integration Quick Start

BotVault has two integrations. This page covers the MCP-based integration, where a local CLI installs a passkey-paired MCP server on your computer and your AI agents see BotVault's credential tools natively. The other integration is API-based (REST + bearer token) — see the API-based Quick Start for that path.

Use the MCP-based integration when your AI agent runs on the same computer where you operate it — Claude Code, Cursor, OpenClaw, any IDE-hosted agent. The agent reads your credentials through MCP tools that appear automatically. No tokens in chat. No copy-paste. Both integrations talk to the same vault, with the same per-bot permissions and audit log.

1. Install the BotVault CLI

Run this on the computer where your AI agent runs:

npx @botvault/cli install

A browser window opens. Click Trust this device when prompted. The CLI:

  • generates a high-entropy PKCE challenge locally,
  • exchanges it with the BotVault server for a bot token,
  • stores the token in your OS keychain (macOS Keychain / Windows Credential Manager / libsecret on Linux),
  • writes a thin-pointer skill to ~/.claude/skills/botvault/SKILL.md,
  • registers the BotVault MCP server in ~/.claude.json (or your IDE's equivalent).

The token never enters your terminal output, your clipboard, or any plaintext file the CLI controls.

2. Restart your AI tool

Quit and reopen Claude Code (or Cursor / OpenClaw). On the next session start, the IDE spawns the BotVault MCP server, which:

  • fetches the latest skill from the server with a conditional GET (304 when nothing changed),
  • exposes two tools to the AI: botvault_list_credentials and botvault_get_credential.

That's it. From this point on, your AI knows how to fetch credentials at the moment of use.

3. What the AI does with it

When your AI needs a credential, it calls one of the MCP tools:

botvault_list_credentials()           → [{ id, label, type }, …]   (no values)
botvault_get_credential({ id })       → { id, label, type, value }

The skill installed at ~/.claude/skills/botvault/SKILL.md instructs the AI to:

  • Always re-list credentials at the start of any task that needs one (permissions can change between conversations).
  • Check BotVault first before asking you to generate or paste a credential.
  • Never log a credential value or echo it back to the user.
  • Fetch on-demand at the moment of use, never cache long-term.
  • Stop the task and tell you to re-authorize if a credential returns expired.

You don't manually configure any of this — the skill is fetched fresh on every session start, so updates from BotVault propagate to every connected user automatically.

4. Troubleshooting

npx @botvault/cli@latest doctor

Reports:

  • OS keychain reachability,
  • Detected IDE(s),
  • Whether SKILL.md and the MCP entry are in place,
  • Local skill version + last refresh time + status,
  • Whether the local skill is behind the server,
  • Whether your bot's token is still valid,
  • How many credentials the bot has access to.

Common cases:

  • Tools don't appear in Claude Code after install. Restart Claude Code (close completely, reopen). MCP servers are spawned on session start.
  • Tool call returns 401. Bot was revoked or token expired. Run npx @botvault/cli install to re-pair.
  • Tool call returns 403 for a credential ID you saw before. Permission was revoked in the dashboard. The AI's skill tells it to re-list automatically — you don't need to do anything.
  • OS keychain unavailable. Type /mcp in Claude Code → reconnect botvault → retry. Almost always works on the second try.

5. What to tell the AI

You don't need to. The skill is loaded into the AI's context automatically by the IDE — that's the point of the install. The AI already knows:

  • Which BotVault tools are available,
  • When to call them (whenever a task needs a credential),
  • The safety rules (never log values, fetch on-demand, etc.).

If you want to read the rules yourself, the skill file is at ~/.claude/skills/botvault/SKILL.md after install. The latest version is also viewable at mybotvault.com/skill.md.

6. Permissions, rotation, security

  • Per-credential permissions are enforced server-side. The bot only sees credentials its grants include.
  • Tokens are revocable. Dashboard → Bots → [your bot] → Tokens → Revoke. Effective immediately. The bot stops working on the next tool call.
  • Re-pair to rotate the token: npx @botvault/cli install --force.
  • Audit log records every read. Dashboard → Settings → Audit Log → filter by bot.
  • Multiple computers: install on each one. Each install pairs its own token; you can grant the same bot to multiple computers, or create separate bots for separate machines (recommended for cleaner audit trails).

For agents that run anywhere other than this computer — LangChain on AWS Lambda, cloud-hosted OpenClaw, GitHub Actions, n8n, Zapier, hosted agents — use the API-based integration instead. That path uses a bot token + REST API and works wherever HTTP works.

For agents that run anywhere other than your computer, see the API-based Integration Quick Start.

Questions or feedback? Send us a message.