run402-mcp

Overview Schema Source Related Servers Discussions Admin

run

Execute TypeScript snippets against the Node SDK in a sandbox to query and manage AI-native Postgres databases; type-checking catches errors before any API call and console logs are captured.

Instructions

Run a TypeScript snippet against the SDK in a sandbox. r is the Node SDK client (@run402/sdk/node); call docs for its reference. The code is the body of an async function: await r chains, and the value of the last expression (or a return) is the result, e.g. (await r.projects.list()).projects.map((p) => p.id). It is type-checked against the SDK before anything runs: a type error comes back with its line and TypeScript's message, and makes no call. No filesystem, process, fetch, timers, or imports; console is captured. Returns { status, value, value_ref, shown, total, logs, logs_ref, calls, duration_ms, wallet, error? }; a large value is stored whole and expand_result pages it. Operations that return or consume a one-time secret (grant keys, Handoff and Invite Keys, project credentials, wallet keys) refuse with SECRET_REQUIRES_CLI naming the exact CLI command to hand the person. Any other operation is a run snippet against r.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "code": "<code>"
    },
    "name": "run"
  }
}

Input Schema

Name	Required	Description	Default
`code`	Yes	TypeScript or JavaScript, run as the body of an async function: top-level await works, and the value of an explicit return or of the last expression statement is the result. `r` is the Node SDK client (`@run402/sdk/node`): await any chain, e.g. `(await r.projects.list()).projects.map(p => p.id)` or `await r.project("prj_…").functions.list()`. The snippet is type-checked against the SDK before anything runs, and a type error makes no call; then types are stripped: no enum, no parameter properties. No filesystem, process, fetch, timers, or imports; `console` is captured.
`timeout_seconds`	No	Deadline for the whole run, 60 s by default and at most 300. An SDK call in flight at the deadline completes on its own; the result lists every call that completed.

Output Schema

Name	Required	Description	Default
`logs`	No
`calls`	No
`error`	No
`shown`	No
`total`	No
`value`	No
`status`	Yes
`wallet`	No
`logs_ref`	No
`value_ref`	No
`type_check`	No
`value_kind`	No
`duration_ms`	No
`logs_dropped`	No
`value_window`	No
`calls_dropped`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv4.126.1Oct 22, 2026

changedInput schema / properties / code / description

Previous value: -"TypeScript or JavaScript, run as the body of an async function: top-level await works, and the value of an explicit return or of the last expression statement is the result. `r` is the Node SDK client (`@run402/sdk/node`): await any chain, e.g. `(await r.projects.list()).map(p => p.project_id)` or `await r.project(\"prj_…\").functions.list()`. Types are stripped, not compiled: no enum, no parameter properties. No filesystem, process, fetch, timers, or imports; `console` is captured."New value: +"TypeScript or JavaScript, run as the body of an async function: top-level await works, and the value of an explicit return or of the last expression statement is the result. `r` is the Node SDK client (`@run402/sdk/node`): await any chain, e.g. `(await r.projects.list()).projects.map(p => p.id)` or `await r.project(\"prj_…\").functions.list()`. The snippet is type-checked against the SDK before anything runs, and a type error makes no call; then types are stripped: no enum, no parameter properties. No filesystem, process, fetch, timers, or imports; `console` is captured."

addedOutput schema / properties / error / properties / diagnostics

Added value: +{
+  "items": {
+    "additionalProperties": true,
+    "properties": {
+      "code": {
+        "type": "string"
+      },
+      "column": {
+        "type": "integer"
+      },
+      "line": {
+        "type": "integer"
+      },
+      "message": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "line",
+      "column",
+      "code",
+      "message"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / error / properties / diagnostics_ref
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / error / properties / diagnostics_total
```
Added value: +{
+  "type": "integer"
+}
```

addedOutput schema / properties / type_check

Added value: +{
+  "additionalProperties": true,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "const": "skipped",
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "reason"
+  ],
+  "type": "object"
+}

AddedSep 25, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so thoroughly: sandbox limits (no filesystem, process, fetch, timers, imports), console capture, type-checking before any call executes, the exact return shape, pagination via `expand_result`, and a named failure mode (SECRET_REQUIRES_CLI with the CLI command to hand off). An agent knows what will happen, what will be blocked, and what comes back.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and result shape are front-loaded, and nearly every sentence adds information (type-check ordering, secret refusal, pagination). The middle section around the return keys and the CLI-refusal rule is dense and slightly run-on, and the async-function-body explanation partially duplicates the `code` schema description, costing a point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a general-purpose execution tool the description is complete: execution semantics, constraints, failure modes, result envelope, and where to go for more (docs, expand_result). Although an output schema exists and technically covers return values, the description's summary of them is still useful framing rather than redundant padding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning about `code`: it runs as the body of an async function, top-level await works, and the last expression is the result, with a concrete example. `timeout_seconds` is left to the schema, but the schema documents it fully, so the small lift above baseline is justified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: running a TypeScript snippet against the SDK in a sandbox, with `r` bound to the Node SDK client. It also implicitly positions itself as the general-purpose escape hatch ('Any other operation is a run snippet against r') and points to `docs` for reference, so an agent can tell it apart from the more specialized siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear routing for two siblings: call `docs` for the SDK reference and use `expand_result` when a value is large. It also signals that anything not covered by a dedicated tool goes here. What's missing is explicit guidance against the remaining siblings (deploy, up, status, whoami, doctor), leaving the agent to infer that this is the fallback rather than a task-specific tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

run