MCP-based Integration Quick Start

BotVault speaks MCP (Model Context Protocol). The primary way to connect is the remote MCP connector at https://mybotvault.com/api/mcp with OAuth — paste the URL into a client that supports custom MCP connectors, approve once, and your agent gets BotVault's credential tools. No tokens copied into the client.

A local CLI (npx @botvault/cli install) remains available when the agent runs on your own computer (Claude Code, Cursor, local IDE). For clients that cannot speak MCP at all, use the API-based Quick Start (REST + bearer token).

Both MCP paths and the API path talk to the same vault, with the same per-bot permissions and audit log.

1. Add the remote MCP connector (primary)

Connector URL:

https://mybotvault.com/api/mcp

Authorization is OAuth 2.1. The client discovers the endpoint, you sign in in the browser, pick which bot and scopes the connection gets, and approve. Headless agents (server/container with no browser) request a short pairing code that you approve from any device. Nothing is copied into the client. See and revoke every connection from Settings → Connections.

Claude.ai custom connector

1. Open Settings → Connectors → Add custom connector
2. Paste https://mybotvault.com/api/mcp
3. Complete OAuth — pick the bot and scopes
4. Confirm the credential tools appear in the session

Claude Directory / portal listing is phase 2 / N/A for v1. Use a custom connector URL as above.

ChatGPT / Developer mode

Eligible plans (Plus, Pro, Business, Enterprise, Edu) on chat.openai.com / chatgpt.com. Developer mode is web-only.

1. Open Settings → Security and login and turn on Developer mode
2. Open Plugins (or Apps) → create a developer-mode app / connector
3. Name it BotVault. MCP server URL: https://mybotvault.com/api/mcp. Authentication: OAuth
4. Click Scan Tools, complete BotVault OAuth (sign in, pick the bot and scopes), then Create
5. In a chat, choose Developer mode from the composer tools menu and enable BotVault
6. Confirm the credential tools appear (list_credentials, get_credential)

On Business/Enterprise/Edu, an admin may need to enable Developer mode in workspace settings first.

Plugins / Apps Directory listing is Phase 2 (BOT-22) — N/A for v1. Use Developer mode as above.

Other remote MCP clients

Grok Bot, Cursor (remote), self-hosted agents, and similar clients that accept an MCP server URL: add https://mybotvault.com/api/mcp, approve OAuth (or pairing code), done.

2. Local CLI (secondary — agent on this computer)

Use this when your AI agent runs on the same computer where you operate it — Claude Code, Cursor, OpenClaw, any IDE-hosted agent.

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.

Restart your AI tool after install. On the next session start, the IDE spawns the BotVault MCP server and exposes the credential tools.

3. Credential tools

Public credential tools (names may appear with a botvault_ prefix depending on the client):

list_credentials()           → [{ id, label, type }, …]   (no values)
get_credential({ id })       → { id, label, type, value }

The skill 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.

4. Troubleshooting

Remote connector

• Tools don't appear after OAuth. Re-open the client or refresh connectors; confirm the connection is listed under Settings → Connections on mybotvault.com.
• Tool call returns 401 / consent loops. Revoke the connection in Settings → Connections and re-add the connector URL.
• Tool call returns 403 for a credential ID you saw before. Permission was revoked in the dashboard. Re-list credentials.

Local CLI

npx @botvault/cli@latest doctor

Reports OS keychain reachability, detected IDE(s), whether SKILL.md and the MCP entry are in place, token validity, and how many credentials the bot can access.

• 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.
• OS keychain unavailable. Type /mcp in Claude Code → reconnect botvault → retry.

5. Permissions, revoke, security

• Per-credential permissions are enforced server-side. The bot only sees credentials its grants include.
• Connections are revocable. Settings → Connections (remote OAuth) or Dashboard → Bots → Tokens → Revoke (CLI/API). Effective immediately.
• Re-pair CLI to rotate the token: npx @botvault/cli install --force.
• Audit log records every read. Dashboard → Settings → Audit Log → filter by bot.

6. Grok Bot and other shared cloud VMs

Grok Bot doesn't run on your computer, so there is nothing to install with the CLI. Connect it as a remote connector:

1. In Grok, open connector settings and add a custom MCP connector.
2. Connector URL: https://mybotvault.com/api/mcp
3. Approve the connection once when Grok sends you to BotVault. Pick which bot it connects as; that bot's grants are exactly what Grok will be able to reach.

The connector is installed account-wide, so every bot you run on Grok shares it. Give the connection a bot whose grants you are happy for all of them to have. You can change it any time in Settings → Connections.

Two things follow from Grok's design:

• All your bots share one computer, one browser profile and one set of CLI credentials. Credentials should be fetched at the moment of use and never saved there.
• A cloud VM cannot reach a password manager on your laptop. A hosted vault is the only kind that works from there.

You should not be asked to re-approve the connection. If Grok keeps sending you back to the consent screen, that's a bug worth reporting to support@mybotvault.com.

Grok Bot's connector behavior was last checked against docs.x.ai on 2026-09-13. The BotVault side of the flow was verified against production on 2026-09-19.

For agents that cannot speak MCP at all — GitHub Actions, n8n, Zapier, some hosted agents — use the API-based integration instead. That path uses a bot token + REST API and works wherever HTTP works. Prefer remote MCP whenever the client supports it.