Skip to main content
MCP lets a client call instabox tools without a CLI in its own environment. The hosted server at https://api.instabox.sh/mcp is the recommended way to connect. To let an agent use the instabox CLI instead, see Coding agents.

​
Connect a client to the hosted server

1

Install the CLI

The command signs you in and installs the instabox CLI. You use the CLI to write the client’s config. The client itself does not need it.
2

Create an API key

The command prints the key once. Set it as INSTABOX_API_KEY in the shell or environment that starts your client.
3

Add the server to your client

The command prints the config file it wrote and tells you to restart the client.
4

Restart the client and try a tool

Ask your client to “list my instabox machines”. It calls list_machines and shows your machines.
Antigravity reads no variables from its config, so --inline-key writes the key itself into the file, readable by you only. Keep such a file out of git.

​
Use the local server without an API key

The client then starts instabox mcp start, a local stdio server. It sends each message to the hosted server with the CLI’s credentials: INSTABOX_API_KEY when set, otherwise your instabox login sign-in, refreshed as needed. It never opens a browser, so sign in once first. The CLI must stay installed where the client runs.
init adds one server named instabox and keeps the rest of the file. It writes to your config, or with --project to the project’s file:
With --hosted, the file holds a reference to INSTABOX_API_KEY, not the key: ${INSTABOX_API_KEY} for Claude Code, ${env:INSTABOX_API_KEY} for Cursor, env_http_headers for Codex, and {env:INSTABOX_API_KEY} for OpenCode.

​
Connect to the hosted server by hand

The URL is https://api.instabox.sh/mcp (Streamable HTTP). Send an API key as X-API-Key: ibk_... or Authorization: Bearer ibk_.... A signed-in CLI’s access token also works as a bearer token. Create a key with instabox keys create --name mcp or on the API keys page. To add the server to Claude Code by hand, run:
A tool call runs the same route as the REST API, so the key’s scopes, your plan, quotas, and rate limits apply as they do there. The server keeps no session. Every request is one JSON-RPC message with its own credentials, and there is no Mcp-Session-Id and no event stream (GET /mcp is 405). Each tool answers JSON. A refused call is a tool error with the API’s code and message, for example missing_scope and the scope it needs. Every tool and its scope is under Reference below.

​
Read these docs over MCP without signing in

https://instabox.sh/docs/mcp is a public MCP server for these docs, so an agent can read them before anything is installed. It needs no account, and it has no access to your machines.
Its tools: search_insta_box searches the docs, query_docs_filesystem_insta_box runs read-only queries over the pages and OpenAPI specs, and submit_feedback reports a problem with a page. The server speaks Streamable HTTP. https://instabox.sh/mcp is the same server.

​
Reference

​
Tools and scopes

A tool given a name instead of an ID looks the machine up first, which needs machines:read.
Lifecycle tools wait up to 120 s by default. wait_seconds is at most 600: a larger value waits 600, and 0 or less means the default. wait: false returns the operation at once.read_file reads up to max_bytes, 256 KiB by default and at most 1 MiB. A larger value is taken as 1 MiB, and 0 or less as the default. For files over 1 MiB, use instabox cp.

API keys

Scopes for the key your MCP client sends.

Coding agents

Give each agent a machine of its own.