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
SANDBOX_AI_ALLOW_HTTP off: the server won't start with a plain http:// address, because it would send the key unencrypted, unless the gateway is local (localhost, a name under .localhost, a loopback address, 0.0.0.0 or ::). Set it to 1 to allow plain http on a network you trust

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

Changes in 0.1.1

This release needs sandbox-ai-sdk 0.1.1, which checks the gateway address more strictly.

  • Plain http to a gateway that isn't local is refused: the server won't start with an http:// address, because it would send the API key unencrypted. That includes http://host.docker.internal. http://localhost, a name under .localhost such as http://app.localhost, other loopback addresses, http://0.0.0.0 and http://[::] still work. To allow plain http on a network you trust, set SANDBOX_AI_ALLOW_HTTP=1. The SDK reports this with the new code insecure_base_url.
  • Requests over plain http to a local address ignore the proxy settings in the environment, such as HTTP_PROXY and ALL_PROXY, and go straight to that address. Local means localhost, a name under .localhost, a loopback address, 0.0.0.0 or ::, the addresses plain http is allowed to without SANDBOX_AI_ALLOW_HTTP=1. A name under .localhost is trusted by its name alone, so make sure it points at this machine. Other addresses use the proxy settings as before.
  • An address with your API key in it is refused at startup. The SDK reports this with the new code key_in_base_url.
  • Addresses that can never work are refused at startup, when the server creates the SDK's Client, with invalid_base_url: a ? anywhere, a port outside 1 to 65535, or whitespace or a % in the host. Before, they failed on the first tool call.
  • An invalid internationalised host, such as an xn-- name that isn't valid punycode, is refused at startup with the usual one-line message instead of a Python traceback.
  • A blank or whitespace-only api_key argument to the SDK raises missing_api_key instead of falling back to SANDBOX_AI_API_KEY. The server leaves api_key out, so it reads SANDBOX_AI_API_KEY as before.
  • Error messages show [redacted] in place of anything in the gateway address that looks like a key, in any case. Tool errors also take out a key the gateway echoes back in any case, not only in lowercase. The SDK's client.base_url and httpx's own request log still show the address as given.
  • uvx keeps the version it fetched first, so run uvx sandbox-ai-mcp@latest once to pick up this update.

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.1

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.1
File Size Uploaded Provenance Actions
sandbox_ai_mcp-0.1.1.tar.gz 12.4 kB Without provenance Details for sandbox_ai_mcp-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 26.5 kB

Release files / sandbox_ai_mcp-0.1.1.tar.gz

Download URL sandbox_ai_mcp-0.1.1.tar.gz
Size 12.4 kB
Tags Source
SHA-256 checksum
How to use checksums
3409c799f57aacfb658bd730b63226744988b338647a0a954e6ddfeeed05f81a
BLAKE2b-256 checksum
How to use checksums
8c11fcd872f7e6921853488a8972e614aeff0c0c353042753916294710843057
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.1-py3-none-any.whl

Download URL sandbox_ai_mcp-0.1.1-py3-none-any.whl
Size 14.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d37b4439ef7f2aa5c503f2ddb36a6de40bdf47ccde693fb2d7a044c07b0ced92
BLAKE2b-256 checksum
How to use checksums
b055fb8654cb657dbbc5b60c7358367c0b4ec78f2cfb8cd02eba43081714d0f5
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.1

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.1 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