Docs/Install with your AI
Get started

Install with your AI

The steps a coding agent follows to add box to the app it runs in, and what a chat app tells you to do instead.

Paste this into Claude Code, Codex, Cursor or Gemini CLI and let the agent do it:

Text
Set up box from https://box.simular.ai/install

https://box.simular.ai/install serves this page: as Markdown to an agent that asks for it or fetches with a tool like curl, otherwise as the HTML page. Setting box up by hand, or in Claude, ChatGPT or Gemini? MCP server has every app's steps.

Steps for the agent

An agent setting box up for someone does the following.

  1. Check first. If box's shell and box_list tools are already available in the session, box is set up; skip to step 4. If the agent is running in the Codex app on Windows, it doesn't run the installer or edit ~/.codex/config.toml: the Codex sandbox on Windows can't write to the Codex home folder. It gives the person the steps in Codex app on Windows and goes on to step 4 once they have signed in.

  2. Add box to the app it is running in with the installer, which also removes box-control, a second server older versions of this setup added:

    Shell
    npx -y @simular-ai/box connect --client <app> --yes

    Put the app's id in place of <app>: claude-code (also the Claude desktop app's Code tab), codex, cursor, opencode, hermes, openclaw or vscode. If it fails (no Node.js, or the app already has a different server named box), say so and add box by hand with the commands below. By hand:

    • Claude Code (also the Claude desktop app's Code tab):

      Shell
      claude mcp remove --scope user box-control >/dev/null 2>&1; claude mcp remove --scope user box >/dev/null 2>&1
claude mcp add --scope user --transport http box https://mcp.box.simular.ai/mcp

    • Codex: write [mcp_servers.box] to ~/.codex/config.toml and leave the rest of the file alone:

      Shell
      node -e '
const fs = require("fs"), path = require("path"), os = require("os")
const file = path.join(os.homedir(), ".codex", "config.toml")
let text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : ""
text = text.replace(/^\[mcp_servers\.box(-control)?\][^\[]*/gm, "")
fs.mkdirSync(path.dirname(file), { recursive: true })
fs.writeFileSync(file, text.replace(/\n*$/, "\n") + "\n[mcp_servers.box]\nurl = \"https://mcp.box.simular.ai/mcp\"\n")
console.log("added box to " + file)
'

    • Cursor: merge into ~/.cursor/mcp.json and keep the servers already there:

      Shell
      node -e '
const fs = require("fs"), path = require("path"), os = require("os")
const file = path.join(os.homedir(), ".cursor", "mcp.json")
const config = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : {}
const { "box-control": _old, ...servers } = config.mcpServers || {}
config.mcpServers = { ...servers, box: { url: "https://mcp.box.simular.ai/mcp" } }
fs.mkdirSync(path.dirname(file), { recursive: true })
fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n")
console.log("added box to " + file)
'

    • Gemini CLI (adding again updates the entry):

      Shell
      gemini mcp add --scope user --transport http box https://mcp.box.simular.ai/mcp

    • DeepSeek Harness: run dsh plugin add https://github.com/simular-ai/box-plugin/releases/download/dsh-v0.2.1/dsh-box.tgz, then tell the person to create a key at https://box.simular.ai/keys and set it themselves, as in DeepSeek Harness. Restarting dsh ends the session, so show the summary in step 4 before they restart.

    • Claude on the web or in the desktop chat, ChatGPT, and the Gemini app: an agent can't add a connector. Give the person only that app's steps from In a chat app (for Claude, the Add to Claude link first), unless they ask about another app, and stop.

  3. Have the person sign in. Only the person can approve, in their browser:

    • Claude Code: they type /mcp, pick box, choose Authenticate, sign in and click Approve.
    • Codex app: they open Settings → MCP servers, select Authenticate next to box, sign in and click Approve.
    • Codex CLI: the agent runs codex mcp login box; the person signs in in the browser that opens and clicks Approve.
    • Cursor: they open Cursor Settings → MCP, click Login next to box, sign in and click Approve.
    • Gemini CLI: they type /mcp auth box, sign in and click Approve.
    • OpenCode: the agent runs opencode mcp auth box. Hermes: hermes mcp login box. OpenClaw: openclaw mcp login box. VS Code signs in when the server starts. The person signs in in the browser and clicks Approve.

    The approval page is https://box.simular.ai/oauth/authorize. It asks which boxes the app may use and for how long; the defaults are fine.

  4. Tell the person box is ready, with these links, and to start a new chat (or restart the app) so the box tools load:

    Also give them two or three of these prompts, word for word, to try in the new chat:

    • "Use box to open Chrome, search Google for "Simular", and summarize the top 3 results."
    • "Use box to open GitHub Trending and tell me what today's top 3 repositories do"
    • "Use box to go to news.ycombinator.com and give me today's top 5 stories in a table"

Rules for the agent: run the commands itself and explain them in plain words; never ask for a key, and never repeat one in the chat; if a step fails, say what went wrong and stop rather than retrying in a loop. npx @simular-ai/box doctor checks the setup and prints a fix; Troubleshooting lists the common problems.

Codex app on Windows

The Codex sandbox on Windows can't write to the Codex home folder, so the person adds box in the Codex app:

  1. In the Codex app, open Settings, then select MCP servers.
  2. Select Add server. Name it box, choose Streamable HTTP and paste the URL below.
  3. Save, then select Restart.
  4. Select Authenticate next to box, sign in to box and approve. In a chat, type /mcp to see it.

The URL is https://mcp.box.simular.ai/mcp. The Codex app, the Codex CLI and the IDE extension share one config, so this covers all three.

DeepSeek Harness (dsh)

dsh can't sign in, so it uses a personal key. The agent installs the plugin; the person creates a key at https://box.simular.ai/keys (Create key under Keys and devices; it is shown once) and sets it in their own terminal, never in the chat:

Shell
dsh plugin add https://github.com/simular-ai/box-plugin/releases/download/dsh-v0.2.1/dsh-box.tgz
export BOX_TOKEN=cb_your_key

The key goes in place of cb_your_key; adding the line to the shell profile keeps it. After a restart, box's tools show up in dsh as mcp__box__*.

In a chat app

Claude on the web or in the desktop chat, ChatGPT and the Gemini app add box as a connector, and only the person can do it. Give them only their own app's steps, unless they ask about another app.

Claude

Give the person the Add to Claude link first: one tap adds box, on a phone too.

Add to Claude

Claude opens with box filled in, on your phone or your computer. Tap Continue, then sign in to box and approve.

If the link doesn't work, by hand:

  1. In Claude (claude.ai or the desktop app), open Settings → Connectors.
  2. Click Add custom connector. Name it box and paste the URL below; leave the advanced settings empty.
  3. Click Connect, sign in to box and approve. Then turn box on in a chat’s tools menu.

The URL is https://mcp.box.simular.ai/mcp.

ChatGPT

Adding happens once on chatgpt.com, in a browser on a computer (the ChatGPT app on iPhone and Android can't add one); after that box works in the ChatGPT app. Link the person to https://box.simular.ai/install?app=chatgpt, which opens these steps, and say that on a phone alone Claude adds box in one tap.

  1. On a computer, open chatgpt.com/plugins (Plugins in ChatGPT’s sidebar). Click Add, then Add custom MCP server.
  2. Name it box. Under Connection, paste the URL below as the Server URL, and choose OAuth as the authentication.
  3. Select I understand and want to continue, then Create as a plugin. Install the plugin, then sign in to box and approve when asked.
  4. In a chat, type @ and pick box, then ask for a task.

The URL is https://mcp.box.simular.ai/mcp. No Add custom MCP server? Their ChatGPT plan or workspace may not allow custom servers yet.

Gemini

Adding happens once on gemini.google.com, on a computer; after that box works in the Gemini app too. Google allows custom apps only for a personal Google Account (not a work or school one), for people 18 or older in the US, in English, with Keep Activity on. Otherwise, Gemini CLI works.

  1. On a computer, open gemini.google.com. Click Settings, then Connected Apps (if you don’t see it, click Personal Intelligence first).
  2. Under Custom apps, click Add a custom app and paste the URL below. Leave Advanced features empty.
  3. Click Next, then sign in to box and approve.
  4. In a chat, type @ and pick box, then ask for a task. Once added, box works in the Gemini mobile app too.

The URL is https://mcp.box.simular.ai/mcp.

Troubleshooting and support

Start with npx @simular-ai/box doctor; Troubleshooting lists the common problems. Support: support@simular.ai.