Metadata-Version: 2.5
Name: sandbox-ai-mcp
Version: 0.1.1
Summary: MCP server for Sandbox AI: lets agents propose changes and read decisions through any MCP client
Author: Sandbox AI
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: mcp<3,>=2.3
Requires-Dist: sandbox-ai-sdk<0.2,>=0.1.1
Description-Content-Type: text/markdown

# 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](https://pypi.org/project/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](https://docs.astral.sh/uv/getting-started/installation/).

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):

```json
{
  "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.
