AI agents

Connect a tool-calling agent to Platinum with the MCP server, the agent skill, llms.txt, or OpenAPI.

Platinum runs agent-generated code in isolated sandboxes. This page shows how to connect a tool-calling agent: the MCP server, the agent skill, llms.txt, and OpenAPI. To drive Platinum from your own code, use the SDK.

Run the MCP server

The MCP server exposes sandbox operations as tools: run code, read and write files, expose a port. It runs over stdio through the pt CLI. The CLI reads your API key from the OS keychain. It writes no token into an agent config file.

Install the CLI and sign in (see CLI):

npm install -g @platinum-dev/cli
pt login

Wire it into your agent

One command points an agent at Platinum:

pt mcp init claude     # or: cursor | windsurf

The command writes the Platinum server entry. It leaves every other key untouched and keeps a .bak file on the first edit. Restart the agent. Then ask it to list Platinum tools.

Agent	Config it writes
`claude`	`.mcp.json` in the current project (`--global` registers user-wide via the `claude` CLI)
`cursor`	`~/.cursor/mcp.json` (`--project` writes `./.cursor/mcp.json`)
`windsurf`	`~/.codeium/windsurf/mcp_config.json`

Configure another client

For any other MCP client, run pt mcp config. Paste the printed snippet into the client config:

{
  "mcpServers": {
    "platinum": {
      "type": "stdio",
      "command": "pt",
      "args": [
        "mcp",
        "start",
        "--permissions",
        "read,exec,write"
      ]
    }
  }
}

The client starts pt mcp start from this entry. The server reads your keychain key at run time.

Tools and permissions

Tools register in four groups. The server never registers a tool outside the granted set, so the model never sees it. A fresh setup grants read,exec,write (11 tools).

Group	Default grant	Tools
read	yes	list sandboxes and templates; read, list, search, and stat files
exec	yes	`run_command` (shell) and `run_code` (python / node / bash / sh)
write	yes	write files, make directories, delete paths
manage	no	create and delete sandboxes, expose ports, set egress policy

Tune the grant on the pt mcp start line:

--permissions read,exec,write,manage picks the groups (env: PT_MCP_PERMISSIONS).
--readonly registers only the read tools.
--confine-sandbox <id> locks every tool to one sandbox. The server refuses a foreign id and drops create and delete.

sandbox_id is optional on every file and exec tool. Omit it, and the server reuses or creates a small default sandbox. A read never creates one. Every result names the sandbox it ran on.

The default pt-base template contains only busybox: no Python, Node, or git. For run_code, use template_list and sandbox_create to select a template with a runtime. See Sandboxes, Exec, Filesystem, and Networking for what each tool does.

Install the agent skill

The agent skill is an SDK cheat sheet for the model. Copy skills/platinum/SKILL.md to the directory where your agent reads skills:

mkdir -p .claude/skills/platinum
cp <repo>/skills/platinum/SKILL.md .claude/skills/platinum/

Use llms.txt and OpenAPI

URL	Contents
`https://platinum.dev/llms.txt`	Docs index — every page with URL and one-line description
`https://platinum.dev/llms-full.txt`	Full docs corpus in one file
`https://api.platinum.dev/openapi.json`	OpenAPI 3.1 spec — every path, body, and auth scheme. Browsable as the API reference