Skip to main content

sandbox-ai-mcp

Lets an agent built on Claude, or any other MCP client, propose changes to business systems such as Salesforce or ServiceNow through Sandbox AI, with no custom code. It runs on your machine over stdio and calls Sandbox AI through the sandbox-ai-sdk package. Python 3.11 and later.

Alpha. This is an early release, and its tools may change before 1.0. It needs access to a Sandbox AI gateway: an agent key and the gateway's address.

Install

Nothing to install first: your MCP client starts it with uvx sandbox-ai-mcp, which fetches it from PyPI. You need uv.

Or install it yourself with pip install sandbox-ai-mcp, and the command is sandbox-ai-mcp.

Set up

  1. In the Sandbox AI dashboard, open Agents, add the agent (or open it), and create a key. Copy it: you only see it once. Give each agent its own key, so you can see who asked for what and pause or revoke one agent without touching the others.
  2. Add the server to your MCP client with the key in SANDBOX_AI_API_KEY and your gateway's address in SANDBOX_AI_BASE_URL. Both are required.

Keep the key in your MCP client's config or environment. Never put it in a prompt, and don't commit it.

Claude Code

claude mcp add sandbox-ai --env SANDBOX_AI_API_KEY=sbx_... --env SANDBOX_AI_BASE_URL=https://your-gateway.example.com -- uvx sandbox-ai-mcp

For a project-scoped .mcp.json that you commit, use "SANDBOX_AI_API_KEY": "${SANDBOX_AI_API_KEY}" so the key comes from each person's environment instead of the file.

Claude Desktop

In claude_desktop_config.json (Settings, Developer, Edit Config):

{
  "mcpServers": {
    "sandbox-ai": {
      "command": "uvx",
      "args": ["sandbox-ai-mcp"],
      "env": {
        "SANDBOX_AI_API_KEY": "sbx_...",
        "SANDBOX_AI_BASE_URL": "https://your-gateway.example.com"
      }
    }
  }
}

If Claude Desktop can't find uvx, use its full path (which uvx), since desktop apps don't always see your shell's PATH.

Cursor

The same mcpServers entry as Claude Desktop, in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

Other MCP clients

Any client that starts stdio servers works. Command: uvx. Arguments: sandbox-ai-mcp. Environment: SANDBOX_AI_API_KEY and SANDBOX_AI_BASE_URL, both required. With the package installed, the command is just sandbox-ai-mcp.

Tools

Tool What it does
propose_change(system, object, fields, record_id?, reason?, idempotency_key?) Proposes a change to one record and returns Sandbox AI's decision. An update when record_id is set, a create when it isn't.
get_decision(change_id) The latest decision for a change, for example after a person approved it. Read-only.

Each result has a summary written for the model (what happened and what to do next) and the full decision: status, mode, and each field's outcome, rules and message. When a call fails, the tool returns an error with a plain-words message and its code, such as agent_paused, plus any details the gateway sent, such as which fields failed on invalid_request. An API key is never included.

idempotency_key is optional. Leave it out on a first try and the SDK makes one. If propose_change times out waiting for an answer, the connection drops after sending, or the gateway answers with a 5xx or something the SDK can't read, the change may already have been made, so the error gives the model the exact key to retry with: "The change may already have been made. Retry with idempotency_key='…' so it isn't made twice." The gateway then returns the first decision instead of making the change twice.

Settings

Environment variable Default
SANDBOX_AI_API_KEY required: the server won't start without it
SANDBOX_AI_BASE_URL required: the address of your Sandbox AI gateway. The server won't start without it

The server writes nothing to stdout except MCP messages, and never logs or prints the key. Problems at startup go to stderr.

What the agent sees

The summary tells the model what to do next. It goes by each field's written flag, so it only says nothing was written when nothing was. When the decision has its own message, as a blocked delete always does, the summary's "Why" starts with it. For example:

  • needs_approval: "Held for approval by grp_sales_managers. It escalates at 2026-10-29T14:02:12Z if nobody decides. phone was written; owner_id waits for a person. Why: owner_id: Owner changes need a manager's OK. Call get_decision with change_id chg_8f2c41 later to see the outcome."
  • needs_approval with every field held: "Held for approval by grp_sales_managers. It escalates at 2026-10-29T14:02:12Z if nobody decides. Nothing was written yet; owner_id waits for a person. …"
  • needs_approval after it escalated: "Held for approval by grp_sales_managers or grp_sales_directors. It expires at 2026-10-30T08:00:00Z if nobody decides. Nothing was written yet; owner_id waits for a person. …"
  • partially_applied, when some fields were written and a rule blocked the rest: "Partly applied: phone written. Why: owner_id: Owner changes aren't allowed for this agent. Don't propose the written fields again. Tell the user which fields weren't changed and why."
  • partially_applied, when the approver declined the rest and left a comment: "Partly applied: phone written. The approver said: "Marcus moves to another region next month". Why: owner_id: Owner changes need a manager's OK. Don't propose the written fields again. Tell the user which fields weren't changed and why."
  • error after part of the change went through: "The system refused part of the change: phone was written; owner_id was not written. Why: owner_id: No such user. Don't propose the written fields again. Tell the user what went wrong, and propose the rest only once the cause is fixed."
  • blocked: "Blocked. Nothing was written. Why: owner_id: Owner changes need a manager's OK. Don't retry the same change; tell the user why."
  • a blocked delete: "Blocked. Nothing was written. Why: Sandbox AI never lets an agent delete records, so nothing was deleted. If this record should go, ask a person to delete it in the system itself. Don't retry the same change; tell the user why."
  • observed: "Watch-only: Sandbox AI recorded what it would have done but wrote nothing, so the change has not been made."

License

Apache-2.0. The full license text is in the LICENSE file included in the package.

Metadata

Release files for sandbox-ai-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sandbox-ai-mcp 0.1.0
File Size Uploaded Provenance Actions
sandbox_ai_mcp-0.1.0.tar.gz 11.3 kB Without provenance Details for sandbox_ai_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sandbox-ai-mcp 0.1.0
File Interpreter ABI Platform Actions
sandbox_ai_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for sandbox_ai_mcp-0.1.0-py3-none-any.whl

Total release size: 24.4 kB

Release files / sandbox_ai_mcp-0.1.0.tar.gz

Download URL sandbox_ai_mcp-0.1.0.tar.gz
Size 11.3 kB
Tags Source
SHA-256 checksum
How to use checksums
cd86da1d8c1189ca11a11859a2f36eabb69294ef465a4fadb6cf818018970b34
BLAKE2b-256 checksum
How to use checksums
eedc2d58d0def771a6dace32d458cdd6cdd1a8c2eb6b5a34a903c5a06ec509f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / sandbox_ai_mcp-0.1.0-py3-none-any.whl

Download URL sandbox_ai_mcp-0.1.0-py3-none-any.whl
Size 13.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
46902d42faaca99f9a2b54d703b1175e1eaa128bb56ddd93b1320e194c6b07b1
BLAKE2b-256 checksum
How to use checksums
5dc698e52c33935498ae601a34bc10730b9ef5346198bdbb7e3e7c2ba4559c1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Security for sandbox-ai-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page