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

Automated HTTP clients

Platinum advertises /automation.md through X-Automation-Policy, the landing page, and model-readable discovery documents. Identify your software in User-Agent; include a public operator email or contact URL only when authorized to disclose it:

User-Agent: ExampleBot/1.0 (contact: https://example.com/bot)

An explicitly authorized public address such as operator@example.com is also suitable. If none is available, omit the contact. Access never depends on providing one. Do not look up, infer, or disclose a private account email, credentials, or identity from session data to comply.

The control plane records complete header values from all client types before authentication, including rejected requests and proxy traffic. The website reports public requests in the background, including the Next-owned /api/chat and /api/search routes. Framework static bundles and image optimization are excluded; API rewrites are collected only by the control plane. Identical web values are coalesced for 60 seconds per warm runtime.

Operators can read the global user_agents table: raw_user_agent is unparsed, case-preserving text; fingerprint is its SHA-256 key; first_seen, last_seen, and observation_count aggregate observations. There is no email extraction, bot classification, IP/account attribution, or public read endpoint. The count is not a total website request count.

Platform admins can browse these observations at /admin#observability/user-agents under Observability → User agents. The default view includes every client type, with complete raw text, first/last seen, and precise observation counts. Search matches literal header text; the optional email-containing filter matches email-like text already in the header, not verified identities or account email addresses. Filters run only when this admin list is requested; ingestion does not parse emails or perform extra work. Pages and manual refresh use the admin-only GET /internal/admin/user-agents.json endpoint. No raw header list is public.

The request path does not await database I/O or hash headers. Flushes batch upserts about every two seconds, and graceful shutdown attempts a final drain. Collection is best-effort, not lossless or zero-cost: each control-plane process retains at most 10,000 entries and 8 MiB of header/fingerprint string payload, including in-flight batches. Oversized/excess observations drop whole, never truncate. Failed batches retry within the same bounds. Crashes, prolonged outages, and shutdown deadlines can lose observations; uncertain write acknowledgements can overcount. Admin-only /metrics exposes collection, write-error, drop, and buffer counters without raw header values.