Clients

The gateway publishes ready-to-paste configuration for the tools people actually use. Nothing on these endpoints is secret — your key is always a placeholder you fill in locally — so they are public and CORS-open.

Step-by-step guides per tool — Cursor, Claude Code, GitHub Copilot, Cline, Continue and Zed — are in Integrations.

VS Code (Copilot Chat, Custom Endpoint)Copy Anchor Link

VS Code's Custom Endpoint language-model provider takes a JSON object describing the models to add to the picker. The gateway serves it prebuilt:

GET https://ai.codai.ro/vscode/chatLanguageModels.json

curl.exe -s https://ai.codai.ro/vscode/chatLanguageModels.json | Set-Clipboard

The picker gets three entries, each a fixed model identity:

The served config sets headers that keep the gateway a transparent transport: X-Codai-Disable-Subagents: 1, X-Codai-No-Recall: 1, X-Codai-Compact: off, plus X-Codai-Thinking: 1 with a per-alias budget and X-Codai-Cache: 1. Copilot owns orchestration and the transcript; the gateway never runs a second agent loop behind it.

Two companion endpoints publish a curated settings baseline: GET /vscode/settings.json (VS Code user settings) and GET /vscode/.copilot/settings.json (Copilot CLI ~/.copilot/settings.json).

GitHub Copilot CLI (BYOK)Copy Anchor Link

Copilot CLI runs in bring-your-own-key mode when COPILOT_PROVIDER_BASE_URL is set — GitHub sign-in is not required. codai is a drop-in provider.

$env:COPILOT_PROVIDER_API_KEY = 'codai_xxxxxxxx'
Invoke-RestMethod https://ai.codai.ro/copilot/env.ps1 | Out-File env.ps1
. .\env.ps1   # dot-source: sets the vars and launches copilot

GET /copilot/config returns the same values as JSON, including the alternative aliases you may use as the wire model (codai-fast, codai-deep, codai-agent, codai-max, codai-explorer, codai-vision) and the capability flags (streaming, tool calling, vision and prompt caching are on; GitHub-hosted memory and remote delegation stay GitHub-routed and are unavailable in BYOK mode).

Persistent memory for BYOK sessionsCopy Anchor Link

BYOK mode loses GitHub's memory. Add the codai MCP server instead:

mkdir -p ~/.codai
curl -fsSL -o ~/.codai/mcp-codai.mjs https://ai.codai.ro/copilot/mcp-bridge.mjs
curl -s https://ai.codai.ro/copilot/mcp.json   # paste `mcpServers` into ~/.copilot/mcp-config.json

The snippet registers a local stdio bridge, not an http server: the CLI does not expand ${ENV} placeholders in http headers, so a remote server with a templated Authorization header sends the literal placeholder and hangs the 60 s handshake. The bridge reads CODAI_API_KEY or COPILOT_PROVIDER_API_KEY from the environment and forwards JSON-RPC to /mcp. Replace ~ in args with your absolute home directory — the CLI does not expand it. The server id is codai (it used to be codai-memory; the bridge URL is unchanged). Set CODAI_MCP_TOOLSETS (for example cards,web or all) to add tool groups to the default set.

Cursor, Continue, Cline, Zed and other OpenAI-compatible toolsCopy Anchor Link

Any client with an OpenAI-compatible provider option works. Set:

If the tool lets you set custom headers, X-Codai-Effort: high or max is the one worth adding. If it offers a model list, it can read GET /v1/models with your key.

Exact settings, file paths and known limits for each tool are in Integrations.

Claude Code and Anthropic-native toolsCopy Anchor Link

Set the Anthropic base URL to the root and the key to your codai key:

export ANTHROPIC_BASE_URL='https://ai.codai.ro'
export ANTHROPIC_API_KEY='codai_xxxxxxxx'
export ANTHROPIC_MODEL='codai'

POST /v1/messages accepts both Authorization: Bearer and x-api-key, so the SDK's default header works unchanged.

MCP serverCopy Anchor Link

The gateway is itself a remote MCP server (Streamable HTTP, spec 2025-11-25, wire-compatible with 2025-06-18):

POST https://ai.codai.ro/mcp

By default tools/list returns the core toolset: memory_search, memory_store, memory_list, memory_graph, memory_forget, chat, list_models, account_get and usage_get (about 9 KB of tool definitions instead of 90 KB). Every other group below is opt-in per connection, so a client only pays context for what it uses:

Select groups with ?toolsets=cards,web on the server URL or the X-MCP-Toolsets header; all lists everything. A tool outside the selection can still be called by name — the selection only trims the list. List tools return a compact page (for example 20 rows, internal fields dropped) unless you pass limit; full detail comes from the matching *_get tool. It also exposes prompts (slash commands), resources (codai://models, codai://memory/recent) and prompt-argument completion.

Resolve tools: resolve_submit (submit a GitHub issue, get a quote), resolve_get (poll the job), resolve_accept (start the fix — debits the quoted price from your wallet, refunded in full if no verified fix; requires confirm_spend: true, and a 402 returns the topup_url) and resolve_attestation (public execution proof). They need an API key; OAuth tokens are refused.

Transcripts tools: list_transcripts, get_transcript, search_transcripts, ask_transcripts (answer across your recordings with citations), export_transcript (md / txt / srt / vtt / json), accept_transcript_prompt (turn a suggested agent prompt into a pending prompt) and transcript_share_create (a read-only public link, optional expiry). Deleting, revoking links, re-running and editing a recording are not exposed. API key only.

Settings tools: settings_get (account-level settings with defaults and their version) and settings_update (deep-merge changes; pass version to refuse overwriting a change made meanwhile on another device), plus the read-only os_gate_policy (whether your organizations allow overriding the OS protection gate). API key only. themes_list lists the curated colour themes (Themes); read-only, no key needed.

Scheduler tools: schedules_list, schedules_runs, schedules_preview (cron or plain words → next runs), schedules_create, schedules_set_enabled, schedules_run_now, schedules_decide (approve / skip a run waiting for you), heartbeats_list, heartbeats_create (the answer holds the secret ping URL, shown once) and heartbeats_set_paused. Deleting a schedule or a heartbeat monitor and approving a terminal command for a host are not tools: a person does them. API key only.

Sessions tools: sessions_list, sessions_get (members, presence and lease), sessions_events, sessions_rename, sessions_archive (archive or restore) and sessions_dispatch (send a message to, or open the session on, one of your devices). Notifications tools: notifications_list, notifications_mark_read and notifications_dismiss. Triggers tools: triggers_list, triggers_update (rename, enable or disable, policy), triggers_test and triggers_events; creating or deleting a trigger and its signing secret stay with you (desktop, phone or API). Deleting a session is not a tool: a person does it. The same commands exist in the CLI as codaid sessions, codaid notifications and codaid triggers. API key only.

Command line for memory and lists: codaid memory list|search|add|rm|clear (rm deletes one memory by id, clear deletes all of them; both ask first unless --yes) and codaid lists list|show|add|export (add without a list shares to the Inbox). Deleting a list is not a command. The agent that codaid run hosts gets the lists_list, list_items and list_add tools, with no delete. The hub has a Memory page (browse, search, add, forget one); desktop and phone show your API keys (edit tags only; create and revoke keys in the hub) and your verified tasks (read-only).

The MCP server also has sandbox tools: sandbox_create (backend v2 by default or v1, TTL, egress none, a pypi/npm preset or an allowlist), sandbox_list, sandbox_exec (a bash line or Python/bash code; returns exit code, stdout, stderr and the receipt), sandbox_files (list, read up to 256 KiB, write up to 1 MiB, or artifacts with sha256 and signed download URLs) and sandbox_kill, plus the v2 tools sandbox_run_code, sandbox_pause, sandbox_resume, sandbox_fork and sandbox_preview. They run with your key, so the l3_sandbox tool level, the caps (3 at once per key, 5 running and 10 paused v2 sandboxes per user, 7,200 exec seconds a day) and metering apply exactly as on the REST API. API key only.

The MCP server also has Vault tools (credentials manager): vault_list (the credentials you exposed to agents: handle {{vault:<slug>}}, title, bound hosts, env var name, sensitivity — never a value), vault_request_use (a policy decision for one use: t1/t2 allowed, t3/t4 returns an approval_id you approve on desktop, phone, watch or the hub, deny with reasons), vault_http (an https call where the handle in a header or the body is replaced on the server, only for items you marked cloud-usable and only to their bound hosts; the response is redacted), vault_approval_status, vault_add_secret (when a credential is missing: you get a single-use link to a codai page where you type the value; clients that declare capabilities.elicitation.url receive it as a -32042 URL elicitation, others as a normal result), vault_add_status (pending, completed with the {{vault:<slug>}} handle, cancelled or expired) and vault_policy_simulate (read-only: replays your past agent uses under draft rules and reports which tiers would change; grants are not replayed). Agents never receive secret values, and revealing or approving stays with you. API key only. codaid vault mcp is a local stdio server with vault_list, vault_run (runs a command with handles injected by the local broker, output redacted), vault_add_secret, vault_add_status and vault_policy_simulate.

The MCP server also has read-only account tools: account_get (plan, credits, task counts), usage_get (spend and requests, optional days and group_by), devices_list and hosts_list (push tokens are never returned), and tasks_list, tasks_get, tasks_stats. Confirming a task is billing, so it stays in the hub, desktop and phone. There is no MCP tool for API keys. The CLI has the same views: codaid account, codaid usage [--days N], codaid keys list|tag (tags only; create and revoke keys in the hub), codaid devices list|hosts, codaid tasks list|show|stats (no confirm) and codaid chat "<prompt>", which streams a reply from codai. Desktop has Overview and Usage pages with the same data as the hub.

More MCP tools: prompts_list and prompts_get (your prompt library, read-only; launching a prompt stays in the apps), profile_get, profile_update (username only) and feedback_submit (thumbs up or down on one of your turns), orgs_list and org_members_list (read-only), and studio_renders_list and studio_assets_list (read-only, no signed download URLs; generation is in the studio toolset below). The CLI matches them: codaid prompts list|show, codaid transcripts list|show|search, codaid profile show|set --username, codaid feedback --up|--down, codaid projects list, codaid team list|members <org-id>, codaid referrals and codaid studio renders|assets. Desktop adds Security (a read-only view; passkeys, two-factor and sessions open in the hub), Projects and Team pages; the phone adds Overview, Cloud projects and Team screens; the hub has an agent Chat page that streams replies from codai and bills them to your account.

Resolve is on every surface now: desktop and the phone list your jobs, show the quote and the proof, submit new issues and accept a quote after a confirmation that shows the price and what pays for it (a short wallet opens the top-up page in the browser; nothing is paid inside the apps). The phone gets a notification when a job is quoted or finishes; desktop shows one for jobs you are watching. codaid resolve list, the MCP tool resolve_list and resolve.list() / resolve.iterate() in both SDKs list your jobs. The SDKs also gain billing (plan, wallet, auto top-up settings, invoices and a low-balance watcher; read-only, checkout stays in the browser) and referrals (your link, stats and invitees, plus redeeming a code and referral consent).

Cards tools: cards_weather, cards_places (billed at Google list price, 200 per day), cards_fx, cards_unfurl, cards_product, cards_route (billed like Google Routes), cards_track and cards_efactura. Each returns { block, provenance } as structuredContent — a ready card block — and its markdown twin as text. API key only.

Web tools: web_search (verified search with domain, publish-date and freshness filters; results as [S1]..[Sn]), web_fetch (one page as clean markdown, optional focus) and deep_research (an async job that returns a cited report; when it is not ready within ~50 s the tool returns the job id, call it again with job_id to collect it). Same names, schemas and rendering as the desktop, phone, VS Code and headless agents, from packages/agent-core/spec/tools-web.json. Your rules apply as on /v1/tools/* (web_search and deep_research gate as web_search, web_fetch as browser_fetch). Metered like the REST endpoints: $3 / 1,000 fast searches, $8 / 1,000 deep, $0.50 / 1,000 fetches, $0.20 per research job; the first 1,000 calls a month are free, and calls inside a codai agent turn are never charged.

Studio tools (?toolsets=studio): Claude, ChatGPT, Cursor or VS Code create and edit creatives, run productions, documents, media operations and music with the same tools as the codai desktop, phone and VS Code agents — same names, descriptions and schemas, from packages/agent-core/spec/tools-studio.json:

• Creatives (free): creative_list, creative_create, creative_outline, creative_get, creative_find, creative_edit (node-id ops against base_seq), creative_lint, creative_lint_fix, creative_versions, creative_revert, creative_templates, creative_save_template, creative_brand_kit_save, creative_restyle, creative_locale_fork, creative_share, creative_review, creative_review_comment, creative_remix, creative_export_lottie, creative_from_document, creative_build, creative_batch, creative_batch_status.
• Paid (money gate: quote and wallet hold first, 402 insufficient_funds when the wallet is short, nothing charged): studio_image, studio_music, studio_video, studio_render, studio_document, studio_document_preview, studio_document_video, creative_frame, creative_render, creative_variants, creative_brand_extract, creative_captions, creative_adapt, creative_localize, creative_produce (brief → finished video, image, presentation, document, spreadsheet, song, carousel or print poster), creative_export_fcpxml, studio_media_op, music_create, music_edit. studio_media_ops and studio_sfx list operations and free sound effects.
• Jobs: a call waits up to about 45 s. A longer render, video, preview, export, frame, media operation or song returns status: "pending" with next_call; call studio_job_status with those arguments to collect the result (it also places a finished music_create / music_edit song on the creative). Productions and batches are polled with creative_produce (production_id) and creative_batch_status.

Results carry asset ids and signed download URLs (valid 1 hour); nothing is saved on your machine. Deleting creatives, templates or brand kits is not a tool. API key only (Authorization: Bearer codai_…); OAuth tokens are refused by these tools for now.

{
  "servers": {
    "codai": {
      "type": "http",
      "url": "https://ai.codai.ro/mcp?toolsets=studio",
      "headers": { "Authorization": "Bearer ${input:codai-key}" }
    }
  }
}

Two ways to authenticate:

• API key — Authorization: Bearer codai_…. Use this from scripts or via the stdio bridge above.
• OAuth 2.1 — clients that support it (VS Code, Claude Desktop, Claude Code, ChatGPT connectors) need no key at all. Point them at the URL; an unauthenticated request returns 401 with a WWW-Authenticate: Bearer resource_metadata=… challenge, and GET /.well-known/oauth-protected-resource/mcp points to auth.codai.ro for self-onboarding.

{
  "servers": {
    "codai": { "type": "http", "url": "https://ai.codai.ro/mcp?toolsets=cards,web" }
  }
}

Send Accept: text/event-stream and a chat tool call streams notifications/progress while in flight, then the JSON-RPC result. Every MCP request passes the same rate limiter as /v1, and tool calls that reach an upstream write a usage record.

Which one should I use?Copy Anchor Link

• You live in VS Code → the Custom Endpoint config. Effort dial, three roles, keychain-stored key.
• You live in a terminal → Copilot CLI BYOK plus the memory bridge.
• You use another editor → its OpenAI-compatible provider with the /v1 base URL.
• You are wiring an agent framework → the SDKs, or the OpenAI/Anthropic SDK against the matching base URL.