# Connect Vecbase to your agent

Use the Vecbase plugin and its remote MCP connection when available. The same account service powers Vecbase models and Robin notes: https://mcp.vecbase.com. A connected plugin does not require the Vecbase CLI or a locally running MCP server. The CLI is optional for terminal workflows, local files and scripts.

## ChatGPT and Codex: plugin and remote MCP

The public directory listing is being prepared; there is no public installation link yet. Do not invent one or claim the plugin is publicly listed. If Vecbase is already installed, reuse it and its bundled Skill; do not also run `setup` or add a second MCP connection.

Install the complete Vecbase plugin, including its Skill and MCP connection. For a private test, use the supplied development ZIP through ChatGPT Plugins → + → Upload plugin ZIP, or the supplied local marketplace in the desktop app. A web development ZIP must reference the registered MCP application; a portable ZIP containing only mcp.json can be restricted to desktop use. Do not treat uploading a package as proof that its tools work on the web.

After installation, use the plugin's Connect action and complete Vecbase OAuth. Do not paste an API Key or ask an end user to register an OAuth application. This account connection includes Vecbase and Robin; users do not need a Workspace or a hosted Agent. Already connected? Reuse that connection in a new conversation.

### Advanced: ChatGPT custom MCP development connection

This tests the MCP server alone, not the bundled Skill. Open ChatGPT Plugins → + → Add custom MCP server. Use https://mcp.vecbase.com, select OAuth, and enter the public client ID vecbase-chatgpt in advanced OAuth settings when requested. Use token endpoint authentication method none; no client secret is needed. Follow the connection and Vecbase consent prompts. Account or workspace policies may restrict this entry. Do not append /mcp or /robin.

The server currently uses a preregistered OAuth client. Automatic registration with DCR or CIMD is not yet implemented, so do not promise that a bare URL plus codex mcp login works on a local client. Use the installed plugin's registered connection; if it is unavailable, the optional Vecbase CLI below provides a separate, supported local workflow.

Browser-only ChatGPT cannot execute installation commands. If a remote tool reports authentication_required, reconnect using the host's OAuth flow; CLI login does not repair an MCP connection. Do not install a CLI merely to sign in to remote MCP.

Verify with a free model-catalog query such as ai_gateway_models_list. Do not generate paid content just to test installation. Use the returned schemas and model capabilities. UI availability depends on the host; tool results remain usable without a panel.

Official connection instructions (checked 2026-10-10):
- https://developers.openai.com/plugins/deploy/connect-chatgpt
- https://learn.chatgpt.com/docs/extend/mcp

## Optional CLI for local agents

Continue below only when the task needs a terminal workflow or the selected host does not have a connected plugin. When the user asks to connect, perform supported local setup yourself; only the user approves account access in their browser.

## Install or update the CLI

The official installer currently supports macOS Apple Silicon. Linux, Windows and Intel Mac binaries are not yet released; do not guess download URLs.

Check `command -v vecbase`, then `$HOME/.local/bin/vecbase`. If missing, download and run the official installer:

```sh
curl --fail --location --proto =https --tlsv1.2 https://vecbase.com/cli/install.sh -o vecbase-install.sh
sh vecbase-install.sh
"$HOME/.local/bin/vecbase" --version
```

The installer reads the current stable release from https://releases.vecbase.com/cli/stable.json, validates each download's SHA-256, and installs into the user's directory without sudo. It preserves credentials and previous releases. If vecbase is not on PATH, use `$HOME/.local/bin/vecbase` for the commands below. Optional `VECBASE_INSTALL_DIR` changes the installation prefix; the default is `$HOME/.local`.

If already installed, run `vecbase update --check` once. When update_available, run `vecbase update`. An unavailable update service does not prevent using an otherwise working installation.

## Use the plugin's instructions

If the Vecbase plugin is already installed, its bundled Skill is sufficient: do not also run `setup` or install a duplicate Skill. CLI installation and its separate browser authorization are needed only for CLI calls. A working MCP connection needs neither.

Without a plugin, the CLI can install a standalone Skill for the requested client:

| Client | Profile | Standalone Skill only |
| --- | --- | --- |
| Codex | codex | `vecbase setup --client codex` |
| Claude Code | claude-code | `vecbase setup --client claude-code` |
| Cursor | cursor | `vecbase setup --client cursor` |
| Gemini CLI | gemini | `vecbase setup --client gemini` |
| GitHub Copilot | copilot | `vecbase setup --client copilot` |
| OpenClaw | openclaw | `vecbase setup --client openclaw` |

Choose only the requested client. `setup --client <client> --status` checks local Skill files; `setup_required` means run setup without --status. `configured` confirms local instructions, not authentication or inference. `skill_conflict` or `custom_configuration` requires reviewing the named location; do not overwrite user-owned instructions. Setup does not modify MCP or other client settings. If the host has not discovered the new Skill, start a new conversation. Client adapters are tested locally, not a claim that every host has passed real-device validation.

## Sign in

Use a stable profile from the table, not a new profile per conversation. Check `vecbase --profile <client> auth status`. If authentication is required:

```sh
vecbase --profile <client> auth login --agent <client>
```

Keep the login process alive for up to 600 seconds. The user confirms in their browser; never approve for them or start duplicate logins. After success resume the original task. Do not rotate a working Key for model, permission, balance or rate-limit errors. Keys remain in the CLI's protected profile store, never in chat, shell arguments or plugin files.

The browser and loopback CLI callback must run on the same computer. On a provisioned headless host use protected VECBASE_API_KEY without printing it. A canceled login needs renewed user intent before retrying. `auth logout` revokes the active Key; use it only when requested.

## Verify with a free query

```sh
vecbase --profile <client> ai-gateway models list --limit 10
vecbase --profile <client> ai-gateway models list --output-modalities image
```

These calls return published models allowed by the current Key. An empty filtered list means no matching model is available to this account, not that every model supports the requested operation. Do not generate paid content just to test installation.

## Call a model

Use `models list --search <name>` and `models get <author/slug>` when choosing a model. Read the relevant command's --help for inputs and outputs:

- Text: `ai-gateway chat completions create` or `ai-gateway messages create`.
- Images: `ai-gateway images create`.
- Speech: `ai-gateway audio speech create`, with --output for the local file.
- Transcription: `ai-gateway audio transcriptions create`, with --file for the audio.
- Video: `ai-gateway videos create`, then `videos get <job-id>` and `videos content <job-id> --output <file>`.

Run these subcommands with the public CLI and the chosen --profile. Use only supported operations and models; command availability alone does not mean a model is enabled. Audio input support on a text model is not proof of transcription endpoint support. Return the real result or structured error, not a guessed success.

For paid requests choose an --idempotency-key before submission and reuse it with identical input after a timeout. Video polling and download use the original job ID, never a new generation. Authentication, balance, permissions and billing remain enforced by the API; no Workspace or hosted Agent is required.

## Updates

Check CLI updates at most once per task. The next CLI invocation uses the updated binary; no server restart is needed. Update plugin instructions through the host plugin manager. Only standalone Skill installations use `setup --client <client>` to refresh their instructions. Neither method changes account credentials.