Skip to content

Connect an AI client

Choose the setup that matches what you want:

  • Quick browser handoff: run centaur send, paste the prepared hand-off into the chosen chat, copy the complete reply, and run centaur again. See Getting Started.
  • Direct connection: zero-copy after setup. The AI calls Centaur to read context, apply an approved change, and undo.

Centaur provides two client integrations:

  • MCP tools let a client read context, prepare a tracked handoff, review a returned patch, apply the approved plan, and undo against one fixed workspace.
  • Commands and skills teach a compatible client how to run the Centaur workflow.
Client Type MCP Skill Notes
Codex desktop/CLI Yes Yes Project-scoped config in trusted projects
Claude Code Yes Yes Private local scope for the current project
Claude Desktop Yes Yes Use MCP for best integration
ChatGPT Web/Desktop Yes (Tunnel) Yes Web requires tunnel, desktop works via skill
Gemini Web/CLI Yes (Tunnel) Yes Web requires tunnel, CLI via MCP
Cursor Yes Yes Setup MCP natively
Windsurf Yes Yes Setup MCP natively
Antigravity Yes Yes -

For existing datasets, the export_data MCP tool takes explicit workspace-relative paths, an optional analysis task, and optional text redact. It creates the same native files and manifest as centaur data and returns their local folder plus the prompt. This still requires attaching files to a remote chat: a local folder path in a tool result does not grant ChatGPT access to its contents. Restart an updated client/server to discover the new tool; no download endpoint is added.

Run this inside the project the client should use:

Terminal window
centaur install

Restart each client after setup. Codex and Claude Code bind the entry to the current project, so installing another repository does not repoint this one.

When installation finishes, Centaur states which route still uses copying and links to the extra ChatGPT web setup.

Use centaur doctor to verify the server handshake and that each configured entry points at this workspace. The final GUI discovery check remains inside the restarted client. Use centaur doctor --redact-paths before sharing the result.

To connect one client, install it explicitly:

Terminal window
centaur install --client codex
centaur install --client claude-code

The combined installer configures every supported target. For one integration, use the lower-level installer and its exact ID.

  • claude-desktop: updates the platform Claude Desktop configuration.
  • claude-code: writes Claude Code’s private local-scope entry for this project in ~/.claude.json. claude is an alias.
  • antigravity: updates ~/.gemini/antigravity/mcp_config.json.
  • antigravity-ide: updates ~/.gemini/antigravity-ide/mcp_config.json.
  • cursor: updates ~/.cursor/mcp.json.
  • windsurf: updates the Windsurf MCP configuration.
  • gemini-cli: updates ~/.gemini/settings.json.
  • vscode: updates this project’s .vscode/mcp.json.
  • codex: updates this project’s .codex/config.toml while preserving unrelated settings and comments. Codex loads it only after the project is trusted.
Terminal window
centaur mcp install --client claude-code
centaur mcp install --client codex
  • antigravity: Antigravity.
  • claude-code: Claude Code. claude and claude-desktop are aliases for the shared Claude skill location.
  • codex: Codex clients that read ~/.agents/skills and the workspace skill.
  • chatgpt: ChatGPT prompt files.
  • agents: clients that read ~/.agents/skills.
  • cursor: Cursor.
  • windsurf: Windsurf.
Terminal window
centaur skill install --client claude-code
centaur skill install --client codex

For an unlisted client, provide its MCP configuration file or command destination directly:

Terminal window
centaur mcp install --config path/to/mcp.json
centaur skill install --output path/to/centaur.md

The terminal, More tools menu, and MCP all use the same profiler. Set the connection string in the environment, then run:

Terminal window
centaur db profile --engine postgres --redact
centaur db profile --engine mongo --sample 500 --format json --redact

MCP clients call profile_database with the same engine (postgres, supabase, or mongo), optional url_env, optional Mongo sample, and optional redact values.

It returns aggregates, never rows. Tables and collections, columns and types, null rates, distinct counts, and the common values of low-cardinality columns. No record leaves the database, so the profile can go into a chat that the data itself must never enter.

Centaur does not store a connection string and does not connect on its own. It reads the URL from an environment variable at call time and runs the client you already have - psql or mongosh - which is where your credentials already live. If the variable is unset, the call fails and tells you so.

Cost differs by engine:

  • Postgres and Supabase scan nothing. ANALYZE already stores per-column null fractions, distinct counts, and most-common values in pg_stats, so Centaur reads the catalog. The numbers cover every row, and a table Postgres has never analysed is reported as such rather than guessed at. The sample option is ignored here.
  • Mongo has no such catalog - the shape only exists in the documents - so it samples sample documents per collection (default 200) and reports how often each key appears. That sample size is the cost dial.

Common values are emitted only for columns with 50 or fewer distinct values. Those are enums and flags; the top values of an email or token column are live user data, and the gate is what keeps them out. The report is scanned for credentials on the way back, and redact: true masks anything found.

For a direct tool connection instead of the file-and-clipboard workflow, use OpenAI Secure MCP Tunnel with Centaur’s existing stdio server:

Terminal window
centaur mcp serve --workspace /absolute/path/to/project

The tunnel is outbound-only, so Centaur does not need a public listener. It requires OpenAI tunnel access and ChatGPT developer-mode access; the ordinary browser workflow above does not.

Claude custom connectors, Gemini custom apps, and other remote MCP clients need an HTTPS endpoint. Start Centaur’s authenticated Streamable HTTP transport locally:

Terminal window
# macOS and Linux
export CENTAUR_MCP_TOKEN="a-random-secret-with-at-least-32-characters"
centaur mcp serve --workspace /absolute/path/to/project --http 127.0.0.1:3765
Terminal window
# Windows (PowerShell)
$env:CENTAUR_MCP_TOKEN = "a-random-secret-with-at-least-32-characters"
centaur mcp serve --workspace C:\absolute\path\to\project --http 127.0.0.1:3765

Keep your CENTAUR_MCP_TOKEN secret and never commit it to source control. Treat it like a password to your local filesystem.

Put an OAuth-capable HTTPS tunnel or reverse proxy in front of http://127.0.0.1:3765/mcp. Configure it to forward Authorization: Bearer <CENTAUR_MCP_TOKEN>, then add the public HTTPS /mcp URL to the web client.

Centaur refuses non-loopback HTTP bindings, missing or incorrect bearer tokens, and unexpected browser Origin headers.

If a trusted proxy adds an Origin header, allow the exact value:

Terminal window
centaur mcp serve --workspace <path> --http 127.0.0.1:3765 --allow-origin <exact-origin>

Repeat --allow-origin for each trusted value.

The HTTP server intentionally does not implement TLS or OAuth. Those internet-facing controls belong at the tunnel or reverse proxy.

The extension in editors/vscode/ provides these commands:

  • Centaur: Start an AI Task
  • Centaur: Apply AI Update
  • Centaur: Check Project
  • Centaur: Undo Last Change
  • Centaur: Export Context for AI

The extension requires the centaur executable on PATH. Download https://getcentaur.pages.dev/downloads/centaur-vscode.vsix, then use Extensions: Install from VSIX in VS Code.

After Start an AI Task, choose ChatGPT, Claude, Gemini, Qwen, Kimi, or DeepSeek in the popup. Centaur opens that chat, copies the prompt, and opens the context folder. You still choose the files and press Send in the browser.

Development builds include an agent job workflow. delegate takes an objective, optional paths and budget_tokens, and output (findings, review, patch, or research). It returns a compact receipt with a durable job_id; the default prepares locally. Set dispatch: true only for an authorized send. Execution requires Windows and runs in a separate process so the MCP connection can close while it works. Research defaults to runner: "desktop", using the configured normal browser and, by default, a review/send step in the companion’s project window. Opt-in companion.send_mode: "automatic" skips that confirmation for an authorized dispatched desktop job. Preparation with dispatch: false remains local. A small native confirmation is the review-mode fallback when the companion executable is missing. The desktop route implements ChatGPT, Claude, Gemini, and Qwen. The zero-file ChatGPT native round trip is verified. Gemini’s native check stopped before submission; a separate coordinator browser test succeeded and reported nativeSent: false. Native verification for Claude, Gemini, and Qwen remains pending. Other outputs default to runner: "own_profile", which requires ChatGPT signed in through centaur browser signin. Supply runner: "desktop" to use the normal browser for those outputs. Kimi, DeepSeek, and custom websites remain preparation-only for agent dispatch; local Ollama keeps its existing route. Public installers may not include these development changes yet.

{"objective":"Review parser.rs for empty-input handling","paths":["parser.rs"],"budget_tokens":8000,"output":"findings","dispatch":true}

Retrieve the outcome with get_job({"job_id":"FULL_JOB_ID","wait_ms":30000}). Continue bounded waits until capture or needs_attention when an automatic return was requested. Research returns a generated summary, sources, and limitations; these remain model claims. Inspect status, next_action, and source freshness. Prepared context is not evidence of sending; an uncertain send must not be retried automatically. Results are compact by default; request include_text: true only when needed. Returned patches go through validation and review, never automatic application. Existing save_task_result can capture a manually returned answer against the same job ID.

Before exporting, compare the workspace returned by get_settings with the intended project. MCP does not switch projects when a different chat opens. Destination, browser, context budget, and research defaults are shared with the desktop Settings window. update_settings changes only supplied future defaults; research_options on delegate overrides one task without changing them.

Companion sending and display preferences are shared too. For example, update_settings with {"companion":{"send_mode":"automatic","show_progress":false}} opts future authorized desktop dispatches into sending without Enter and hides their progress. get_settings exposes both settings.companion and factory_defaults.companion. Each prepared job snapshots these preferences; changing defaults does not alter an existing job. Automatic mode can still focus the browser and require sign-in or website verification. It does not auto-apply patches or retry failed or uncertain sends. A task typed into the companion still requires context review and Run.

budget_tokens gates the estimated complete outgoing prompt. Automatic dispatch stops if required context and instructions exceed it; prepare-only mode reports the estimate. .centaur/jobs/ holds local job records, prompts, and failed raw captures. Exclude it from version control. A failed raw capture can be retrieved explicitly with include_text: true, but is not a validated result.

An MCP client can read the configured workspace, prepare a tracked handoff, preview the exact returned diff, apply that workspace-bound plan after approval, and revert a Centaur session. It cannot choose a different workspace through a tool argument.

prepare_handoff stores the destination, expected response type, repository revision, and file fingerprints. It does not open a browser, touch the clipboard, or send code. If Centaur detects possible credentials, preparation stops until the caller requests redaction. A GUI can call get_pending_review to read the newest browser-captured plan for this workspace. Pass the returned handoff_id to preview_patch, show the diff to the user, then pass the reviewed plan_id to apply_patch only after approval. A changed source file or different workspace invalidates the plan.

Clients with global configuration still need a separate named entry for a second project:

Terminal window
centaur mcp install --client cursor --workspace ~/code/api --name centaur-api

Read Safety and recovery before exposing a connector beyond the local machine. See Edge cases for pagination, proxy origins, and multiple workspaces.

Website privacy