# Use Ablit as your IDE model

Point your IDE's OpenAI-compatible provider at Ablit. Create a key in **Settings → API access**, enter the values below, and select `ablit-flash` (Ablit Flash), `ablit` (Ablit Max), or any `Cheap` (`cheap-...`) or `Ablit Stable` (`stable-...`) model. All listed models are also available directly in Ablit web chat. MCP setup is optional.

| Setting | Value |
| --- | --- |
| Provider / API format | OpenAI-compatible Chat Completions |
| Base URL | `https://ide.ablit.app/api/v1` |
| Models | `ablit-flash` (Ablit Flash), `ablit` (Ablit Max), `Cheap` (`cheap-...`), `Ablit Stable` (`stable-...`) |
| API key | Your Ablit key from Settings |
| Authentication | `Authorization: Bearer YOUR_ABLIT_API_KEY` |

Ablit Max costs **$0.75 per million input tokens**, **$0.075 per million cached input tokens**, and **$3 per million output tokens**. The original Ablit keeps its existing pricing.

API access is available on every plan with a key that has the `run` permission. Model usage consumes your Ablit account credits. The complete key is shown once. Save it in your IDE's secret storage; never commit it or paste it into a prompt.

## Cursor setup

[Open the step-by-step setup guide](https://ablit.app/docs/api#cursor-setup) to see the exact values beside the corresponding Cursor settings. The labeled setup illustration uses Ablit’s real base URL and model name; paste your own API key.

1. Open **Cursor Settings → Models** and find the OpenAI API key settings.
2. Paste your Ablit API key and enable the provider.
3. Enable **Override OpenAI Base URL** and enter `https://ablit.app/api/v1`.
4. Add a custom model named `ablit-max`, then select it in the chat model picker.
5. Open your project and start a conversation. For agent work, use the IDE's agent mode with the tools you want enabled.

Use the base URL above, without `/chat/completions` at the end. Cursor adds the endpoint. Use exactly `ablit-max` or `ablit`; selecting another provider's model does not select Ablit.

Your Cursor version and organization policy determine which custom-provider features are available. Custom API keys do not replace Cursor Tab. See [Cursor's API key guide](https://cursor.com/help/models-and-usage/api-keys) for its current limits. If the base URL control is unavailable in your client, use a client that exposes OpenAI-compatible provider settings.

## Cursor tools and connection checks

The router accepts nested and flat function tools, including MCP names containing dots. It uses collision-safe names upstream and restores the original names in returned calls. Your IDE owns tool execution, approval prompts, local files, MCP connections and mode changes. Ablit does not execute host tools on your computer.

Custom tools such as `ApplyPatch` are represented upstream by a function with one `input` string. The returned custom call contains that exact raw input, including patch newlines and Unicode. Custom calls are buffered until complete; ordinary function calls stream incrementally. Grammar descriptions guide generation but are not a guarantee that the model's patch applies. The IDE must validate and approve edits. Existing function-based edit tools keep their original schemas and arguments; no fuzzy edits are silently converted into patches.

Tool history must include each call's real result. Exact duplicate result messages are deduplicated; orphaned, conflicting or missing results return an actionable 400. The router never invents a successful tool result. JSON schemas are preserved, including references, rather than removing validation constraints.

`GET https://ablit.app/api/v1/health` checks router liveness; it does not check provider availability. `GET /models` requires your API key. Empty-message validation requests use a minimal greeting and consume normal model credits. Streams send keepalive comments during inference after upstream admission. Send support the response's `X-Request-Id`, not your API key or private code.

Cursor's API-key traffic passes through Cursor's servers for final prompt building. Its BYOK privacy policy and feature availability apply. This integration does not enable Cursor Tab, Bugbot or cloud agents. Protocol compatibility is tested separately from any particular Cursor release.

## Continue in VS Code or JetBrains

Add this model to your Continue configuration. If you already have a configuration, merge the model entry into its existing `models` list.

```yaml
name: Ablit
version: 1.0.0
schema: v1
models:
  - name: Ablit Max
    provider: openai
    model: ablit-max
    apiBase: https://ablit.app/api/v1
    apiKey: ${{ secrets.ABLIT_API_KEY }}
    roles: [chat, edit, apply]
    capabilities: [tool_use]
```

Set `ABLIT_API_KEY` in Continue’s secret configuration, such as your private `~/.continue/.env` file, then select Ablit. See [Continue’s local secrets reference](https://docs.continue.dev/faqs#managing-local-secrets-and-environment-variables). `tool_use` tells Continue that this custom model supports function calling. Your existing project context and enabled MCP tools stay configured in Continue. See [Continue's configuration reference](https://docs.continue.dev/reference) and [OpenAI provider setup](https://docs.continue.dev/customize/model-providers/top-level/openai).

## Other IDEs and tools

Choose **OpenAI-compatible** or **custom OpenAI provider**, and enter the base URL, key, and model from the table above. The client must support Chat Completions. A setting that only accepts an Anthropic endpoint or OpenAI Responses API endpoint is a different protocol.

For an application using the OpenAI JavaScript SDK:

```js
import OpenAI from "openai";

const ablit = new OpenAI({
  baseURL: "https://ablit.app/api/v1",
  apiKey: process.env.ABLIT_API_KEY,
});

const stream = await ablit.chat.completions.create({
  model: "ablit-max",
  messages: [{ role: "user", content: "Write a TypeScript function that parses a CSV row." }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta.content ?? "");
}
```

## Your IDE's tools and MCP connections

The IDE sends the model its enabled tool definitions, conversation, and relevant project context. Ablit returns standard function calls. The IDE executes them using its own permissions and approval controls, then sends the results back to the model. This includes MCP tools when the IDE exposes them through its model tool interface.

You do not need to register those tools again in Ablit or run the local bridge for this provider connection. Tool names, JSON schemas, call IDs, arguments, and results stay in the Chat Completions tool format. The available tools depend on what your IDE includes in each request. A provider URL cannot access tools that the IDE does not expose, or unlock features the IDE reserves for its own models.

## ABLIT CODE CLI

ABLIT CODE is Ablit's coding agent for the terminal: it reads, edits and runs code in your project on your own machine and uses your Ablit API key for the model. It ships as one binary for macOS (Apple Silicon and Intel), Linux (x64 and arm64) and Windows (x64), and offers `ablit-flash`, `ablit` and every Cheap and Ablit Stable router model from the list above. The full guide is at [ablit.app/cli](https://ablit.app/cli).

```bash
curl -fsSL https://ablit.app/install | bash
```

```powershell
irm https://ablit.app/install.ps1 | iex
```

Then connect your key and start in a project:

```bash
ablit-code auth login ablit   # paste your Ablit API key once; or export ABLIT_API_KEY
cd my-project && ablit-code
```

The CLI refreshes its model list and prices from `https://ablit.app/api/catalog/opencode`, so new router models appear without reinstalling. Your code stays on your machine; only the conversation and the files the agent reads go to the model API.

## Chat Completions API

Set your API key without putting it in shell history:

```bash
read -rsp 'Ablit API key: ' ABLIT_API_KEY; echo
export ABLIT_API_KEY
```

List models or send a streaming request:

```bash
curl --fail-with-body https://ablit.app/api/v1/models \
  -H "Authorization: Bearer $ABLIT_API_KEY"

curl --no-buffer --fail-with-body https://ablit.app/api/v1/chat/completions \
  -H "Authorization: Bearer $ABLIT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"ablit-max","messages":[{"role":"user","content":"Write a TypeScript function that parses a CSV row."}],"stream":true}'
```

`GET /models` returns `ablit-flash` (Ablit Flash), `ablit` (Ablit Max), and all listed `Cheap` (`cheap-...`) and `Ablit Stable` (`stable-...`) models (with `ablit-max` retained as a legacy alias for Ablit Flash). Every listed model can also be used in Ablit web chat and supports the following native request format:

| Field | Supported values |
| --- | --- |
| `messages` | `system`, `developer`, `user`, `assistant`, and `tool` roles. Text strings or arrays of text parts; assistant tool calls and tool results retain their IDs. |
| `tools` | Up to 128 function definitions, preserving names, descriptions, parameter JSON schemas, and optional `strict`. |
| `tool_choice` | `auto`, `none`, `required`, or a named function from the supplied tools. |
| `parallel_tool_calls` | Boolean. |
| `stream` | Boolean. Streaming returns OpenAI-style SSE chunks and `[DONE]`. |
| `stream_options` | With streaming, `{ "include_usage": true }` requests a usage frame. |
| `max_tokens` or `max_completion_tokens` | One of these fields, from 1 to 32,768. Default output budget: 4,096 tokens. |
| Sampling | `temperature`, `top_p`, `presence_penalty`, `frequency_penalty`, `stop`, `seed`, and `logit_bias`. |
| Other | `reasoning_effort` (`low`, `medium`, `high`), `user`, and `n: 1`. |

### Images, files and IDE code edits

The `ablit` router accepts image/file parts in `user` and `tool` message content arrays alongside text. It routes supported images to Ablit's vision model and passes its observations to the main coding model. Source code, text files, diffs, tool IDs, function schemas and edit arguments remain text and are preserved. Your IDE executes its own file-read/edit tools; the router does not silently turn them into cloud file edits. Replayed assistant tool calls may include Cursor's numeric `index`; this transport metadata is normalized before the provider request.

```json
{"model":"ablit-max","messages":[{"role":"user","content":[
  {"type":"text","text":"Match this screenshot and update my component."},
  {"type":"image_url","image_url":{"url":"data:image/png;base64,BASE64_IMAGE"}},
  {"type":"file","file":{"filename":"component.tsx","file_data":"BASE64_UTF8_FILE"}}
]}]}
```

Images support PNG, JPEG, WebP and GIF, supplied as base64 data URLs or public HTTPS URLs. Private-network destinations and redirects are blocked. Files accept base64 `file_data` (raw base64 or a MIME data URL) or an owned Ablit media UUID in `file_id`. External-provider file IDs are not interchangeable with Ablit IDs. UTF-8 code/text and PDFs with extractable text are supported. Scanned PDFs need their pages supplied as images; other binary document formats must be exported to text or images first. Unsupported inputs fail explicitly and are never silently discarded.

At most eight media parts are accepted, subject to the context budget. Each downloaded media file is bounded to 8 MiB; aggregate downloaded media to 16 MiB. Inline base64 must also fit the 4 MiB JSON-body limit. Extracted file text is limited to 160,000 characters, within the combined 200,000-character conversation limit. A request that cannot fit returns an error rather than truncated source.

Vision analysis consumes account credits separately from main-model tokens, at the existing native-model markup. Both require funded credits, including administrator API keys. The main response's `usage` describes main-model tokens; vision charges appear separately in account usage. Repeated identical images with the same user-question context reuse a private account-scoped analysis cache after a successfully billed analysis. Cache reuse does not trigger another vision charge. In-flight/uncertain provider charges remain reserved for reconciliation; provider calls are not automatically retried. Extracting text locally has no separate model charge; the resulting context is metered when the main model processes it.

Sampling and reasoning controls are forwarded to the underlying model. This endpoint accepts text, function tools, image inputs and supported file content. Audio inputs, legacy `functions`/`function_call`, structured `response_format`, embeddings, and the Responses API are not supported. Unknown top-level metadata and private reasoning-history fields are removed before dispatch. Unsupported semantic features such as `response_format`, audio and legacy functions return an explicit error rather than silently changing the requested output.

Requests accept up to 1,000 messages, with a combined serialized message budget of 200,000 characters. Supplied tool definitions have a combined serialized budget of 100,000 characters. The native Chat Completions JSON request must fit 4 MiB; other API routes retain their 1 MiB limit. Media preprocessing is bounded to 120 seconds and the total native request to 285 seconds. Client cancellation or disconnect aborts this model request; a cloud task already submitted through a cloud tool has its own durable lifecycle.

Function calling uses `tools` with function definitions and optional `tool_choice`. When the response contains `message.tool_calls`, execute each permitted call in your client, append the assistant message, and append one `role: "tool"` message per result with the matching `tool_call_id`. Send the conversation again for the next model turn. Streaming clients receive incremental `delta.tool_calls`; assemble each call's arguments before executing it.

Ordinary model inference is managed by your client and ends when that client disconnects. To keep work running after you close the IDE, ask Ablit to start a cloud task through its cloud tools, or submit work through the runs API below. Retain the returned run ID to check the result later.

## Ablit cloud capabilities from your IDE

The model API also makes Ablit cloud tools available according to your API key’s scopes. These tools run on Ablit’s server. Your IDE’s own tool calls are still returned to the IDE to execute.

| Cloud tools | Key permissions |
| --- | --- |
| `ablit_cloud_start_task` | `run` and `read` |
| `ablit_cloud_get_task` | `read` |
| `ablit_cloud_cancel_task` | `cancel` |
| `ablit_cloud_list_knowledge`, `ablit_cloud_read_knowledge` | `knowledge` |
| `ablit_cloud_workspace_list`, `ablit_cloud_workspace_read`, `ablit_cloud_workspace_write` | `workspace` |
| `ablit_cloud_execute_kali` | `execute` and `read` |

New keys default to `run`, `read`, and `cancel`. Select additional permissions when creating a key if you want direct knowledge, workspace, or Kali tools available. The cloud agent started with `start_task` has its own agent tool access, including installed skills, connected services, and subagents. Cloud orchestration is bounded to six model rounds per request. A long task returns a run ID that can be inspected in later turns.

Ablit omits automatic cloud tools when adding them would exceed the request’s tool-count, tool-schema, or message budget. Your client’s original tools remain available.

To use only the tools supplied by your client, send the header `X-Ablit-Cloud-Tools: off`. In Continue, add it under the model’s `requestOptions.headers`:

```yaml
requestOptions:
  headers:
    X-Ablit-Cloud-Tools: "off"
```

Local project files and the remote Kali workspace are separate. Cloud tools can use the files you explicitly provide or place in the remote workspace. A durable cloud task can continue after disconnection; local IDE tool calls need the IDE to stay available.

## Authentication and permissions

Send `Authorization: Bearer YOUR_ABLIT_API_KEY` on every API request. JSON requests use `Content-Type: application/json`.

| Scope | Enables |
| --- | --- |
| `run` | Use the model API, list models, and start cloud agent runs |
| `read` | Read run status, events and output |
| `cancel` | Request cancellation |
| `knowledge` | List and read built-in knowledge |
| `workspace` | List, read and write remote workspace files |
| `execute` | Submit a remote Kali command job |

**The `run` scope is not read-only.** It permits the delegated agent to use its full tools, including connected services, subagents, and Kali commands. Grant it only to clients you trust to initiate that work. Direct workspace and command MCP calls have supplementary `workspace` and `execute` scope checks; omitting those scopes does not make a delegated agent run read-only. Keys are account-scoped; knowing another account's run or workspace ID does not grant access.

Keys expire after 90 days by default and can be configured for up to 365 days. Revoke them in Settings. Revocation and expiry reject subsequent authenticated requests. Changing plans does not disable your keys. Revocation or expiry also asks active workers to stop on their next credential check. An in-flight tool or side effect may still finish. Use explicit cancellation when you want to stop a particular run and inspect its final state.

## Optional: durable cloud runs

Set a secret in your shell without placing it in shell history:

```bash
read -rsp 'Ablit API key: ' ABLIT_API_KEY; echo
export ABLIT_API_KEY
```

Submit work:

```bash
curl --fail-with-body https://ablit.app/api/v1/runs \
  -H "Authorization: Bearer $ABLIT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Inspect this workspace and summarize its README.","workspaceId":"YOUR_WORKSPACE_ID","idempotencyKey":"readme-summary-001","effort":"medium"}'
```

`POST /runs` returns HTTP 202 with `{ "id", "conversationId", "workspaceId", "status" }`. Store the run ID. Status is `queued`, `running`, `completed`, `cancelled`, or `failed`. Optional input fields are `workspaceId`, `conversationId`, `idempotencyKey`, and `effort` (`low`, `medium`, `high`). The `Idempotency-Key` HTTP header can also carry the key. Reuse a key when retrying the same submission; use a new key for different work. Idempotency protects submission retries, not exactly-once execution of every action inside a task. Repeated or interrupted external actions may need reconciliation.

Poll or cancel with the returned ID:

```bash
curl --fail-with-body 'https://ablit.app/api/v1/runs/YOUR_RUN_ID?after=0' \
  -H "Authorization: Bearer $ABLIT_API_KEY"

curl --fail-with-body -X DELETE https://ablit.app/api/v1/runs/YOUR_RUN_ID \
  -H "Authorization: Bearer $ABLIT_API_KEY"
```

`GET /runs/{id}` returns the run's current status, events and output. The response contains `id`, `conversationId`, `status`, `error`, `events`, `hasMore`, `cursor`, and `output`. Events are `{ "id", "event" }` entries, with up to 250 per page. The optional `after` is a nonnegative event cursor; retain the returned `cursor` for the next poll. If `hasMore` is true, fetch the next page. Output is the accumulated text, capped at 1,000,000 characters. Poll every few seconds and back off on rate limits. `DELETE` returns `{ "ok": true }` when it records a cancellation request; a false value can mean the task is already terminal. Cancellation is cooperative: already completed tool calls cannot be undone. Read the final run status rather than assuming a cancellation request instantly stopped all activity.

Jobs continue after a disconnected client. This is not a guarantee of completion: provider failures, exhausted credits, execution limits, worker interruption, or other failures can end a job. Interrupted work is surfaced as a failure rather than silently claiming success. Read the status and output before deciding whether to retry a task that might have side effects.

## Optional: forward local MCP tools to a cloud run

The optional local bridge exposes the MCP servers you explicitly configure to an Ablit run. It supports stdio and Streamable HTTP. It does **not** discover Cursor's private built-in tools, read an IDE's active tool registry, or reproduce native IDE tool approval prompts. You can point it at the same MCP servers you use in your IDE, subject to those servers' permissions and connection limits.

Use Node.js 20.11 or newer. [Download the local MCP bridge](https://ablit.app/downloads/ablit-ide-bridge.zip); no access to the Ablit source repository is required. The archive includes the bridge, README, example configuration, and an exact dependency lockfile. Its MCP SDK dependency is pinned to `@modelcontextprotocol/sdk` 1.32.1.

Extract it into a private directory and install the locked dependencies:

```bash
curl -fLO https://ablit.app/downloads/ablit-ide-bridge.zip
unzip ablit-ide-bridge.zip
cd ablit-ide-bridge
npm ci
```

These commands assume a shell with `curl` and `unzip`; you can also download and extract the archive with your operating system's file tools.

Create a private JSON configuration file outside your repository. Replace the uppercase path and host placeholders with your actual MCP server details. These examples do not install a server:

```json
{
  "mcpServers": {
    "local": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/YOUR/MCP/server.mjs"],
      "env": { "PROJECT_ROOT": "${env:ABLIT_LOCAL_REPO}" },
      "timeoutMs": 120000
    },
    "remote": {
      "url": "https://YOUR_MCP_HOST/mcp",
      "headers": { "Authorization": "Bearer ${env:MY_MCP_TOKEN}" }
    }
  }
}
```

Remove entries you do not need. `command`, `args`, `cwd`, `env`, `url`, and `headers` support `${env:NAME}` interpolation. Stdio servers inherit the local process environment except `ABLIT_API_KEY`; explicit `env` entries override inherited values. HTTP servers support explicit headers; interactive OAuth sign-in is not implemented by this adapter. Endpoints require HTTPS, with HTTP allowed only for loopback development. Credentials in URLs, query strings, and fragments are rejected. Server stderr is suppressed to avoid accidentally printing credentials.

Grant the Ablit key `run` and `read` scopes (`cancel` is useful for separate cancellation). Local server credentials stay in the local process/configuration; only tool definitions, call arguments and results cross the Ablit API. Tool results and final agent output may contain sensitive data. Configure narrowly scoped local tools: forwarding a filesystem, terminal or private-network MCP server grants the cloud run that server's actual capabilities, even though Ablit's own remote sandbox cannot reach your private LAN. The bridge executes requested registered tools automatically without a per-call approval dialog.

```bash
node index.mjs \
  --config "$HOME/.config/ablit/mcp.json" \
  --prompt "Use the configured local MCP tools to inspect my project and summarize it." \
  --workspace default \
  --state "$HOME/.local/state/ablit/project-run.json"
```

The bridge lists every configured server's tools and registers distinct names derived from `server__tool` plus a short stable hash. The cloud agent sees an additional `ide_` namespace prefix. It polls pending calls, dispatches them to the matching MCP server, and forwards the complete structured SDK result. It prints activity and final task text, not configuration, headers, or raw tool arguments. Keep it running while the task needs local tools. Cloud execution can continue after disconnection, but local tool calls cannot complete while the bridge is offline and expire after five minutes.

To resume, use the printed run ID, the same config, and the original state file:

```bash
node index.mjs \
  --config "$HOME/.config/ablit/mcp.json" \
  --run-id YOUR_RUN_ID \
  --state "$HOME/.local/state/ablit/project-run.json"
```

The state file is written with private permissions and contains run IDs, tool-call hashes, and complete results. Keep it out of version control and retain it for reconnects. It may contain private data returned by your tools. Completed local calls are replayed from the saved result instead of executed again. A crash during a call has an uncertain outcome: the bridge returns an explicit error for that call on resume and does not automatically repeat it. This is not an exactly-once guarantee. A process failure before a side effect or its result was recorded may still require manual reconciliation. If submission lost its response before a run ID was saved, repeat the original command and state file to reuse the persisted idempotency key. Do not delete state to resolve that uncertainty.

Only one process may use a state file. If a crash leaves a `.lock` file, verify the recorded process has stopped before removing that lock. Ctrl-C stops the local bridge; it does not cancel the cloud run. Cancel through `DELETE /runs/{id}` if needed. Reconnection requires an unchanged advertised tool catalog; choose a new task and state file if you intentionally change tools.

The direct registration limit is 64 tools and 200,000 bytes of combined definitions. Larger catalogs automatically use two discovery tools: `search_local_tools` returns matching original aliases, descriptions and complete schemas; `call_local_tool` invokes a discovered alias with its arguments. Search supports `query`, `offset` and `limit` (default 5, maximum 20), returns `nextOffset`, and reduces page size to stay within the result budget. All configured tools remain discoverable. Individual descriptions are limited to 4,000 characters and object input schemas to 32,000 UTF-8 bytes; oversized individual definitions are rejected without silently changing schemas. A result request, including its ID and wrapper, must fit 200,000 UTF-8 bytes. An oversized tool result becomes an explicit error instead of truncated JSON. Local call timeout defaults to 120 seconds, can be configured with `timeoutMs` from 100–600,000 milliseconds, and never exceeds the pending call's remaining deadline. Binary/image/audio MCP results can be transported as JSON within the limit, but the current text agent does not interpret them as native multimodal input; prefer textual summaries.

### Client-tool API

An advanced client can supply `clientTools: [{ "name", "description", "inputSchema" }]` with `POST /runs`. These are callbacks to that client, separate from OpenAI function calling. Retrieve pending calls with `GET /runs/{id}/tools` (`read` scope):

```json
{
  "calls": [
    {
      "id": "TOOL_CALL_ID",
      "name": "REGISTERED_TOOL_NAME",
      "arguments": { "text": "example" },
      "expiresAt": "2026-10-18T12:05:00.000Z"
    }
  ]
}
```

Return the result to `POST /runs/{id}/tools` with both `run` and `read` scopes:

```json
{
  "id": "TOOL_CALL_ID",
  "result": {
    "content": [{ "type": "text", "text": "Tool output" }],
    "structuredContent": { "ok": true }
  },
  "isError": false
}
```

The result is stored as a `result`/`isError` envelope. Identical repeated submissions are accepted; a different result for the same completed call is rejected. Expired, cancelled and closed calls reject results. Polling only returns calls belonging to your account and the requested active API run.

## Optional: connect Ablit as an MCP server

Use `https://ablit.app/api/v1/mcp` when you want an IDE agent to delegate a task to Ablit’s cloud agent or call its workspace tools. This is separate from selecting Ablit as the IDE’s model. Remote MCP requires Streamable HTTP and bearer-header authentication.

### Cursor: optional cloud MCP

Set `ABLIT_API_KEY` in the environment inherited by Cursor. Add this server to your personal `~/.cursor/mcp.json`, or merge it into an existing `mcpServers` object:

```json
{
  "mcpServers": {
    "ablit": {
      "url": "https://ablit.app/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:ABLIT_API_KEY}" }
    }
  }
}
```

Restart Cursor if you changed its launch environment. Enable Ablit in Cursor's MCP settings and ask its agent to use `start_task`, then `get_task` with the returned task ID. Review tool permissions before approving execution. A remote MCP connection adds tools to the IDE agent; it does not replace Cursor's native chat model.

The configuration uses the URL, headers, and environment interpolation documented in [Cursor's official MCP guide](https://cursor.com/docs/mcp). Client configuration may vary by release and organization policy.

### VS Code: optional cloud MCP

For VS Code's built-in MCP configuration, add the following to `.vscode/mcp.json`, or use **MCP: Add Server**. The password input keeps the secret out of the JSON file:

```json
{
  "servers": {
    "ablit": {
      "type": "http",
      "url": "https://ablit.app/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:ablit-api-key}" }
    }
  },
  "inputs": [
    {
      "id": "ablit-api-key",
      "type": "promptString",
      "description": "Ablit API key",
      "password": true
    }
  ]
}
```

Start the server from VS Code's MCP controls and enable its tools in the agent session. See the [official MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) and [server setup guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers). Different VS Code agent harnesses can read different configuration files; the example above targets built-in VS Code MCP, not every extension or harness.

## Legacy cloud chat adapter

The model `ablit-agent` retains the previous cloud-agent Chat Completions adapter. Use `ablit-max` or `ablit` for a native IDE model connection. The legacy adapter accepts text messages and delegates the conversation to a cloud run; it does not accept client function tools. It accepts `conversation_id`, `workspace_id`, and `reasoning_effort` for cloud runs. A nonstreaming legacy request may return HTTP 202 with a run receipt after 50 seconds. Legacy streams observe the cloud run for up to 50 seconds; use the returned `X-Ablit-Run-Id` to poll continued work.

## Optional: Ablit cloud MCP tools

The endpoint accepts JSON-RPC POSTs using Streamable HTTP. Clients must send `Accept: application/json, text/event-stream` and `Content-Type: application/json`, alongside the bearer token. It supports initialization for protocol versions `2025-03-26` and `2024-11-05`. There is no separate legacy SSE GET endpoint.

| Tool | Arguments | Scope |
| --- | --- | --- |
| `start_task` | `prompt`, optional `workspaceId`, `conversationId`, `idempotencyKey`, `effort` | `run` |
| `get_task` | `id`, optional `after` | `read` |
| `cancel_task` | `id` | `cancel` |
| `list_knowledge` | Optional `query`, `offset`, `limit` | `knowledge` |
| `read_knowledge` | `id`, optional `file`, `offset`, `limit` | `knowledge` |
| `workspace_list` | `workspaceId`, optional `path` | `workspace` |
| `workspace_read` | `workspaceId`, `path` | `workspace` |
| `workspace_write` | `workspaceId`, `path`, `content` | `workspace` |
| `execute_kali` | `workspaceId`, `script`, optional `idempotencyKey` | `execute` |

Use `tools/list` for the current schemas. Start and execute tools return job receipts; use `get_task` to observe progress and retrieve output. Unknown argument fields are rejected. `list_knowledge` accepts a search `query` of up to 200 characters, a nonnegative `offset`, and a `limit` from 1–100 (default 50). It returns `{ "items", "total", "offset", "nextOffset" }`; each item contains `id`, `name`, `description`, and `kind`. Pass `nextOffset` as the next request’s `offset` until it is null. Knowledge reads support bounded slices; use the catalog's IDs rather than guessing filesystem paths. Built-in knowledge is available to the delegated agent and through the catalog. Installed skills belong to your account and supply instructions to your runs; they do not install programs or grant extra tools.

## Limits and billing

- Every plan can create API keys. Requests require available credits; administrator accounts do not bypass API usage billing.
- Requests are limited to 60 per minute per key. Each account can have two active cloud API jobs.
- A positive credit balance is required to start cloud work. Model requests reserve credits against their input and output budget before execution, then settle against reported token usage. Unused reserved credits are returned after settlement, subject to monthly credit expiry. If the provider does not report usage, accounting uses the reserved input estimate and maximum output budget; the charge never exceeds that reservation. API keys use the account’s existing credits.
- Native Chat Completions JSON bodies are limited to 4 MiB; other API request bodies are limited to 1 MiB. Submitted prompts are bounded to 200,000 UTF-8 bytes; individual operations can impose tighter limits. Native model requests and legacy cloud chat have separate message validation; see the Chat Completions reference above.
- Remote workspace files are UTF-8 text, up to 200 KB per file. Paths stay within the selected remote workspace.
- Direct Kali command jobs accept scripts up to 8,192 bytes and request up to 1,800 seconds (30 minutes), subject to the configured runner limit. This requires a chat-worker image built with the 30-minute execution path; deploying the web app alone does not update the worker. They require a positive credit balance; shell execution uses bounded included compute.
- The Kali root filesystem is read-only except for writable `/workspace`, `/root`, and `/usr/local`. Account/workspace state persists; Git, Node/npm, and Python workflows are supported in that environment.
- Workspace storage has a monitored 2 GiB budget, not a hard filesystem quota. Commands are stopped when the workspace exceeds that budget or shared disk space is low. The sandbox has a 256 MiB `/tmp`; where supported, resource controls limit it to one CPU, 1 GiB memory and 256 processes.
- The IDE sandbox can reach the public internet. Host, private-network and metadata-network destinations are blocked; it cannot access your private LAN. Existing platform network and tool policies still apply. Installing skills or connecting an IDE does not bypass those policies.

## Errors and troubleshooting

Errors contain an `error` object with a human-readable `message` and a machine-readable `code` or `type`. Check HTTP status before interpreting a JSON response as a successful run. MCP also returns JSON-RPC protocol errors or tool errors; inspect the tool result, not just HTTP 200.

| HTTP status | Meaning and action |
| --- | --- |
| 400 | Invalid JSON, arguments, unsupported fields or model. Check the request schema. |
| 401 | Missing, invalid, expired or revoked key. Create or rotate the key. |
| 402 | Insufficient credits. Check your account balance. |
| 403 | Missing scope, ineligible plan or access denied. Check permissions and plan. |
| 404 | Resource is not available to this account, or does not exist. Check the returned IDs. |
| 409 | A conflict, such as a submission/key limit. Read the error code before retrying. |
| 413 | Request, file or script too large. Reduce the payload. |
| 415 | Unsupported content type. Send JSON. |
| 429 | Rate or active-job limit. Respect `Retry-After` when present and back off. |
| 5xx | Server or execution infrastructure failure. Inspect existing run state before retrying side effects. |

If MCP cannot connect, confirm the HTTPS endpoint, bearer header, client environment and organization policy. If a tool is absent, refresh tool discovery and check scopes. If a model request fails, check its requested model and API format. MCP is a separate cloud-tool connection, not a replacement for the model provider. A successful connection does not prove every IDE workflow is compatible.