# MCP server
Keln runs an [MCP](https://modelcontextprotocol.io) server at `https://mcp.keln.ai/mcp`. Point an MCP client at it,
and your AI assistant can run code in [sandboxes](index.md) and search and read the web. There is nothing to install.
- **Transport:** Streamable HTTP, MCP's standard transport for remote servers, over HTTPS only.
- **Sign-in:** your Keln [API key](../platform/authentication.md), sent as `Authorization: Bearer <key>`.
- **Billing:** each tool call is a call to the Sandbox API or the web API, made with your key. Keln bills it to your
balance at the usual [sandbox](index.md#pricing) and [web](../capabilities/web-search.md) prices, under your key's
rate limits. The MCP server itself adds no charge.
The examples read your key from the environment:
```bash
export KELN_API_KEY=sk-keln-…
```
## Connect a client
### Claude Code
```bash
claude mcp add --transport http keln https://mcp.keln.ai/mcp \
--header "Authorization: Bearer $KELN_API_KEY"
```
This saves the server and your key in your Claude Code settings. To share the server with a team without sharing a
key, put it in `.mcp.json` at the project root; each person then sets `KELN_API_KEY`:
```json
{
"mcpServers": {
"keln": {
"type": "http",
"url": "https://mcp.keln.ai/mcp",
"headers": { "Authorization": "Bearer ${KELN_API_KEY}" }
}
}
}
```
### Cursor
In `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project:
```json
{
"mcpServers": {
"keln": {
"url": "https://mcp.keln.ai/mcp",
"headers": { "Authorization": "Bearer ${env:KELN_API_KEY}" }
}
}
}
```
Cursor reads `KELN_API_KEY` from the environment it starts in, such as your shell profile.
### Codex
```bash
codex mcp add keln --url https://mcp.keln.ai/mcp --bearer-token-env-var KELN_API_KEY
```
Or in `~/.codex/config.toml`:
```toml
[mcp_servers.keln]
url = "https://mcp.keln.ai/mcp"
bearer_token_env_var = "KELN_API_KEY"
```
The Codex IDE extension and the ChatGPT desktop app read the same file.
### VS Code
GitHub Copilot in VS Code reads `.mcp.json` at the workspace root, or `~/.copilot/mcp-config.json` for every
workspace:
```json
{
"mcpServers": {
"keln": {
"type": "http",
"url": "https://mcp.keln.ai/mcp",
"headers": { "Authorization": "Bearer ${KELN_API_KEY}" },
"tools": ["*"]
}
}
}
```
### Other clients
Any client that speaks Streamable HTTP and lets you set a request header can connect. Give it the URL
`https://mcp.keln.ai/mcp` and the header `Authorization: Bearer <your Keln API key>`.
### From an API
Agents built on another provider's API can use the server through that API's MCP support. The provider's servers then
call mcp.keln.ai with your Keln key, so use a key you can revoke on its own.
OpenAI Responses API, in `tools`:
```json
{
"type": "mcp",
"server_label": "keln",
"server_url": "https://mcp.keln.ai/mcp",
"headers": { "Authorization": "Bearer <your Keln API key>" },
"require_approval": "never"
}
```
Anthropic Messages API, with the header `anthropic-beta: mcp-client-2025-11-20`:
```json
{
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.keln.ai/mcp",
"name": "keln",
"authorization_token": "<your Keln API key>"
}
],
"tools": [{ "type": "mcp_toolset", "mcp_server_name": "keln" }]
}
```
## Tools
| Tool | What it does |
|---|---|
| `create_sandbox` | Starts a sandbox and waits until it runs. It stops after `timeout_s`, 300 seconds by default, and its files go with it. |
| `list_sandboxes` | Lists your sandboxes, newest first, by state or by your labels. |
| `get_sandbox` | Reads one sandbox: its state, expiry, size and open ports. |
| `set_sandbox_timeout` | Moves a sandbox's stop time, up to 24 hours from its creation or last resume. |
| `pause_sandbox` | Pauses a sandbox with its memory, processes and files kept. Billing stops until it resumes. |
| `resume_sandbox` | Runs a paused sandbox again, as it was. |
| `delete_sandbox` | Stops a sandbox and deletes it. Billing ends, and its files are gone. |
| `run_command` | Runs a shell line and returns its exit code, stdout and stderr. With `background: true` it returns a command ID at once. |
| `command_output` | Reads a background command's output so far, or waits for it to exit. |
| `send_stdin` | Writes to a background command's stdin, and can close it. |
| `kill_command` | Kills a command. |
| `write_file` | Writes a file as text or base64, making any missing folders. |
| `read_file` | Reads a file as text or base64. A PNG, JPEG, GIF or WebP image of up to 5 MB comes back as an image your assistant can see. |
| `list_files` | Lists a folder. |
| `open_port` | Gives a port a preview URL, private or public. See [Preview ports](ports.md). |
| `web_search` | Searches the web and returns ranked pages with the passages that matched. |
| `web_fetch` | Reads up to 5 pages as clean text, or only the passages that answer a question. |
A sandbox bills while it runs. Ask your assistant to delete or pause a sandbox when it's done with it.
## Limits
- **Request size:** up to 12 MB.
- **Files:** `write_file` takes and `read_file` returns files of up to 8 MB, as text or base64. Read or write a larger
file in parts with `run_command`.
- **Command output:** `run_command` and `command_output` return up to 30,000 characters of stdout and of stderr
(`max_output_chars`, which you can set up to 100,000). Past that they keep the start and the end, and say how much
they cut.
- **Line endings:** output arrives line by line, so a last line printed without a newline gets one. See
[Output format](commands.md#output-format).
- **Long commands:** run anything longer than about a minute with `background: true`, then read it with
`command_output`.
## Errors
- **A missing or unknown key** gets `401` with `WWW-Authenticate: Bearer`, before any tool runs.
- **A tool that fails** returns a result marked as an error. Its text starts with the API's error code, such as
`sandbox_not_found: …`. The codes are listed under [Sandbox API errors](../api/sandboxes.md#errors).
- **A command that exits non-zero** isn't an error: its exit code is in the result.
## Privacy
The server keeps nothing between requests and never stores your key. Sandbox data follows [Data handling](data-handling.md), and web queries follow
[Web search privacy](../capabilities/web-search.md#privacy).
MCP server
Keln runs an MCP server at https://mcp.keln.ai/mcp. Point an MCP client at it,
and your AI assistant can run code in sandboxes and search and read the web. There is nothing to install.
Transport: Streamable HTTP, MCP's standard transport for remote servers, over HTTPS only.
Sign-in: your Keln API key, sent as Authorization: Bearer <key>.
Billing: each tool call is a call to the Sandbox API or the web API, made with your key. Keln bills it to your
balance at the usual sandbox and web prices, under your key's
rate limits. The MCP server itself adds no charge.
This saves the server and your key in your Claude Code settings. To share the server with a team without sharing a
key, put it in .mcp.json at the project root; each person then sets KELN_API_KEY:
Any client that speaks Streamable HTTP and lets you set a request header can connect. Give it the URL
https://mcp.keln.ai/mcp and the header Authorization: Bearer <your Keln API key>.
From an API
Agents built on another provider's API can use the server through that API's MCP support. The provider's servers then
call mcp.keln.ai with your Keln key, so use a key you can revoke on its own.
OpenAI Responses API, in tools:
{"type":"mcp","server_label":"keln","server_url":"https://mcp.keln.ai/mcp","headers":{"Authorization":"Bearer <your Keln API key>"},"require_approval":"never"}
Anthropic Messages API, with the header anthropic-beta: mcp-client-2025-11-20:
{"mcp_servers":[{"type":"url","url":"https://mcp.keln.ai/mcp","name":"keln","authorization_token":"<your Keln API key>"}],"tools":[{"type":"mcp_toolset","mcp_server_name":"keln"}]}
Tools
Tool
What it does
create_sandbox
Starts a sandbox and waits until it runs. It stops after timeout_s, 300 seconds by default, and its files go with it.
list_sandboxes
Lists your sandboxes, newest first, by state or by your labels.
get_sandbox
Reads one sandbox: its state, expiry, size and open ports.
set_sandbox_timeout
Moves a sandbox's stop time, up to 24 hours from its creation or last resume.
pause_sandbox
Pauses a sandbox with its memory, processes and files kept. Billing stops until it resumes.
resume_sandbox
Runs a paused sandbox again, as it was.
delete_sandbox
Stops a sandbox and deletes it. Billing ends, and its files are gone.
run_command
Runs a shell line and returns its exit code, stdout and stderr. With background: true it returns a command ID at once.
command_output
Reads a background command's output so far, or waits for it to exit.
send_stdin
Writes to a background command's stdin, and can close it.
kill_command
Kills a command.
write_file
Writes a file as text or base64, making any missing folders.
read_file
Reads a file as text or base64. A PNG, JPEG, GIF or WebP image of up to 5 MB comes back as an image your assistant can see.
list_files
Lists a folder.
open_port
Gives a port a preview URL, private or public. See Preview ports.
web_search
Searches the web and returns ranked pages with the passages that matched.
web_fetch
Reads up to 5 pages as clean text, or only the passages that answer a question.
A sandbox bills while it runs. Ask your assistant to delete or pause a sandbox when it's done with it.
Limits
Request size: up to 12 MB.
Files:write_file takes and read_file returns files of up to 8 MB, as text or base64. Read or write a larger
file in parts with run_command.
Command output:run_command and command_output return up to 30,000 characters of stdout and of stderr
(max_output_chars, which you can set up to 100,000). Past that they keep the start and the end, and say how much
they cut.
Line endings: output arrives line by line, so a last line printed without a newline gets one. See
Output format.
Long commands: run anything longer than about a minute with background: true, then read it with
command_output.
Errors
A missing or unknown key gets 401 with WWW-Authenticate: Bearer, before any tool runs.
A tool that fails returns a result marked as an error. Its text starts with the API's error code, such as
sandbox_not_found: …. The codes are listed under Sandbox API errors.
A command that exits non-zero isn't an error: its exit code is in the result.
Privacy
The server keeps nothing between requests and never stores your key. Sandbox data follows Data handling, and web queries follow
Web search privacy.