Skip to main content
Glama
Sign In
mcp-box

mcp-box

by EnzoTironi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

mcp-box

Private MCP server that turns the ascii Box API into tools an external agent can drive. ChatGPT, Claude, Cursor, or Grok is the agent. The Box is the Linux machine.

POST /prompt is never used. Agents run shell and file tools only.

Install

npm install
cp .env.example .env   # set BOX_API_KEY
npm run typecheck
npm test

Related MCP server: can-see

Run

stdio (Claude Desktop, Cursor, Grok local):

npm run start:stdio
# or
npx tsx src/stdio.ts

Streamable HTTP (local Inspector, or behind tunnel-client):

npm run start:http
# listens on http://127.0.0.1:8787/mcp when PORT=8787 in .env

ChatGPT: use OpenAI Secure MCP Tunnel, not a public Cloudflare URL. See docs/chatgpt.md.

# after tunnel-client is installed and CONTROL_PLANE_API_KEY is set
export CONTROL_PLANE_TUNNEL_ID=tunnel_6a7290ef51b88191af7b32deba8e0640
tunnel-client run \
  --control-plane.tunnel-id "$CONTROL_PLANE_TUNNEL_ID" \
  --mcp.server-url http://127.0.0.1:8787/mcp

Then in ChatGPT: Criar app → Conexão Túnel → select mcp-box → Sem autenticação.

Environment

Variable

Default

Purpose

BOX_API_KEY

(required for live)

Box dashboard API key; never sent to the MCP client

BOX_BASE_URL

https://ascii.dev/api/box/v1

API base

MCP_BOX_MODE

isolated

isolated or trusted

ALLOW_WRITES

true

When false, deny non-read tools

HOST

127.0.0.1

HTTP bind address

PORT

3333

HTTP port

MCP_BOX_AUDIT_PATH

stderr (trusted)

Optional audit JSONL path

See .env.example.

Trust modes

Mode

noEnv on create/fork

Account secrets

Audit log

Force stop

isolated (default)

always true

blocked

off

denied

trusted

may be false

allowed via env / account

JSON lines

allowed with confirm: true

Isolated boxes cannot act on your account secrets. Use them for untrusted agent work.

Trusted mode records every tool call (timestamp, tool, boxId, outcome). Desktop URLs and tokens are redacted in logs.

Tools

Tool

Read-only

Notes

box_create

no

Default size small; TTL 3600s; waits until ready

box_list

yes

Optional state filter

box_get

yes

Desktop URL redacted in summary

box_exec

no

timeoutSeconds capped at 60

box_exec_background

no

Convention under .mcp-box-jobs/

box_job_status

yes

Poll pid/exit/log tails

box_read_file

yes

Relative paths only

box_write_file

no

utf8 or base64

box_download_artifact

yes

Base64, max ~2MB

box_desktop

yes

Secret URL; do not log full value

box_stop_and_wait

no

Requires confirm: true

box_resume

no

Wait until ready

box_fork

no

Isolated forks are noEnv

box_interrupt

no

Best-effort; prompt-oriented

There is no box_prompt tool.

Background jobs

Box has no native shell job API. Background work is:

  1. Write a launcher under .mcp-box-jobs/<jobId>/

  2. nohup the command; store pid and logs

  3. Poll with box_job_status

Clients

Grok template

npm run grok:template          # small box: grok CLI + OAuth + EnzoTironi/skills + zoen-skills/pstack
npm run grok:diagnose -- bx_…  # resume + smoke; REARCHIVE=1 to stop again

Current template: go-zoen / bx_sb5sbxzz (see docs/grok-template.md). Fork for ChatGPT work with Grok + skills + go-zoen.

ChatGPT write caveat

Full write MCP tools in ChatGPT generally need Business / Enterprise / Edu. Pro is often read-only for connectors. Confirm your plan before relying on ChatGPT as the primary write agent.

Security

  • Keep BOX_API_KEY on the host only.

  • Prefer isolated mode unless you intentionally need account secrets.

  • Redact desktop URLs (_token) from logs and tickets.

  • Bind HTTP to localhost unless you add auth (v1 has no OAuth).

Non-goals (v1)

  • Multi-tenant OAuth

  • Wrapping POST /prompt

  • Native job queue

  • Cloudflare Workers deploy

Development

npm test
npm run typecheck
npm run smoke              # fake client tools/list
LIVE_BOX=1 npm run smoke   # live create → exec → write/read → stop

License

Private / unlicensed unless you add one.

Available Tools

14 tools
box_createA

Create a Box cloud computer. Isolated mode always uses noEnv. Waits until ready when possible.

Inputs: env, name, type, ttlSeconds.

box_desktopB
Read-only

Get a secret-bearing desktop/noVNC URL. Never log the full URL.

Inputs: boxId (required), vnc, publicAccess.

box_download_artifactA
Read-only

Download an artifact as base64 (max ~2MB). Prefer box-side tools for larger files.

Inputs: path (required), boxId (required).

box_execC

Run a shell command in a ready box. timeoutSeconds is capped at 60.

Inputs: boxId (required), command (required), cwd, timeoutSeconds.

box_exec_backgroundA

Start a long command via nohup under .mcp-box-jobs// and return immediately.

Inputs: boxId (required), command (required).

box_forkA

Fork a box from its latest snapshot. Isolated forks always use noEnv.

Inputs: boxId (required), env.

box_getA
Read-only

Get box state. Desktop URLs are redacted in the summary field.

Inputs: boxId (required).

box_interruptA

Best-effort interrupt of prompt work on a box (not shell background jobs).

Inputs: boxId (required).

box_job_statusB
Read-only

Poll background job state from .mcp-box-jobs// files.

Inputs: boxId (required), jobId (required).

box_listB
Read-only

List boxes for the account.

Inputs: limit, state, cursor.

box_read_fileA
Read-only

Read a file relative to the box workdir.

Inputs: path (required), boxId (required), encoding.

box_resumeA

Resume an archived box and wait until ready.

Inputs: boxId (required).

box_stop_and_waitA
Destructive

Stop a box and wait until archived. Requires confirm:true. force requires trusted mode.

Inputs: boxId (required), confirm (required), force.

box_write_fileB

Write a file relative to the box workdir.

Inputs: path (required), boxId (required), content (required), encoding.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.8/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct operation: lifecycle (create/list/get/resume/stop/fork), execution (exec/exec_background/job_status/interrupt), file access (read/write/download), and desktop. The overlap between exec and exec_background is clear from their descriptions—one is synchronous with a timeout, the other is asynchronous via nohup.

    Naming Consistency5/5

    All tools share the 'box_' prefix and use lowercase verbs or verb_noun patterns (e.g., box_create, box_read_file, box_stop_and_wait). The naming is uniformly descriptive and follows a recognizable convention throughout.

    Tool Count5/5

    14 tools is well-scoped for a cloud computer management server, covering lifecycle, command execution, job handling, file operations, and desktop access without being excessive. Each tool serves a distinct purpose and earns its place.

    Completeness4/5

    The surface covers the major workflows: box lifecycle (create, get, list, resume, stop, fork), command execution (foreground, background, interrupt, job status), and file operations (read, write, download). Minor gaps exist, such as no explicit delete/destroy tool and no direct retrieval of background job stdout/stderr, but agents can work around these with existing tools.

    Resources

    Related MCP Connectors

    Related MCP Servers