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
- 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.
- Add the server to your MCP client with the key in
SANDBOX_AI_API_KEYand your gateway's address inSANDBOX_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_approvalwith 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_approvalafter 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."errorafter 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 includeshttp://host.docker.internal.http://localhost, a name under.localhostsuch ashttp://app.localhost, other loopback addresses,http://0.0.0.0andhttp://[::]still work. To allow plain http on a network you trust, setSANDBOX_AI_ALLOW_HTTP=1. The SDK reports this with the new codeinsecure_base_url. - Requests over plain http to a local address ignore the proxy settings in the environment, such as
HTTP_PROXYandALL_PROXY, and go straight to that address. Local meanslocalhost, a name under.localhost, a loopback address,0.0.0.0or::, the addresses plain http is allowed to withoutSANDBOX_AI_ALLOW_HTTP=1. A name under.localhostis 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, withinvalid_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_keyargument to the SDK raisesmissing_api_keyinstead of falling back toSANDBOX_AI_API_KEY. The server leavesapi_keyout, so it readsSANDBOX_AI_API_KEYas 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'sclient.base_urland httpx's own request log still show the address as given. - uvx keeps the version it fetched first, so run
uvx sandbox-ai-mcp@latestonce 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.