Skip to content

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.

The examples read your key from the environment:

export KELN_API_KEY=sk-keln-…

Connect a client

Claude Code

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:

{
  "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:

{
  "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

codex mcp add keln --url https://mcp.keln.ai/mcp --bearer-token-env-var KELN_API_KEY

Or in ~/.codex/config.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:

{
  "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:

{
  "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.