Tools and Code Mode
How Grid82 generates MCP tools from its route registry, tool annotations, pagination, intentional exclusions, and Code Mode sandboxes.
Every Grid82 MCP tool mirrors an operation in the REST API, generated from the exact same route registry. Adding an endpoint ships the matching MCP tool and CLI command on the same day.
Tool naming and annotations
Operation IDs convert dots to _: records.list becomes records_list, schema.get becomes schema_get, and rules.simulate becomes rules_simulate. Every App API and Builder API reference page displays its exact MCP tool name.
Each tool carries standard MCP annotations so clients know when to prompt before acting:
| Annotation | Meaning |
|---|---|
readOnlyHint | Operation only reads data or metadata |
destructiveHint | Deletes records or resources, or mutates many records at once (such as records_delete_many or sql_execute) |
idempotentHint | Calling twice with the same inputs produces the same state |
Pagination and errors
- Cursors. Paged list tools return
{ data, meta }. Keep passingmeta.nextCursorascursorwhilemeta.hasMoreistrue, and narrow queries withfilterorwherefirst to conserve context window tokens. - Tool errors. Permission refusals and validation errors return as MCP tool results (
isError: true) carrying the structuredcodeandmessage, rather than transport failures.
Operations intentionally excluded from MCP
| Operation | Why it is not an MCP tool | Use instead |
|---|---|---|
files.upload | MCP tools pass JSON; uploads stream raw file bytes | Upload bytes via REST or grid82 files upload, then attach the returned file descriptor with records_update |
| Creating or revoking keys | An agent credential must not be able to mint persistent successor tokens | Create and revoke API keys in a browser session |
| Password setup links | Grants account sign-in authority | Builders generate links from the Studio UI or authenticated session |
| Add-on and top-up checkout | Purchasing plans or credit packs requires an interactive human browser session | Use the Studio Billing page in a browser |
Code Mode (/mcp/code)
When a task requires filtering, joining, or batching dozens of calls, connect an agent to /mcp/code (https://{suite}.grid82.app/mcp/code or https://studio.grid82.app/mcp/code). Code Mode replaces individual operation tools with two tools:
search: Filters the caller’s masked OpenAPI document using JavaScript expressions (detail: "compact"returns a lightweight index first; filtered queries return full parameter schemas).execute: Runs one TypeScript/JavaScript snippet inside an isolated JavaScript sandbox that authenticates calls as you with zero outbound internet access.
| Code Mode sandbox limit | Value |
|---|---|
| Execution timeout | 30 seconds |
| API requests per run | 100 |
| Script source size | 64 KB |
| Return payload size | 256 KB |
Large page writes
Writing a large Interface page via MCP sends every character of TSX source through model tokens. For substantial page refactors, update code via PUT .../pages/{pageId}/code (grid82 pages code-set --code @Page.tsx).