Metadata-Version: 2.5
Name: sandbox-ai-mcp
Version: 0.1.0
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
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 |

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.
