Tool reference
The 58 tools OpZero exposes over MCP, grouped by what they are for. You will rarely name one directly — Claude picks them from what you ask — but this is the map of what is possible.
help.Orientation
Where to start when you are not sure what is possible, what you already have, or why a call was rejected.
helpread onlyThe full tool catalogue with usage notes. Pass a topic to narrow it to one area or a single tool.
helpread only| Parameter | Type | Description |
|---|---|---|
| topic | string | Optional filter: a section (e.g. "deploy", "assistants", "projects") or a tool name (e.g. "deploy_react_artifact"). Unknown topics return the list of valid topics. |
get_system_statusread onlyYour plan, usage, active projects, recent deployments, and how much of each per-plan cap is consumed. The cheapest way to confirm the connection works.
get_system_statusread onlyTakes no parameters.
ask_opzero_assistantread onlyAsk a question about your own account in plain language. Answers over your recent activity, and renders an adaptive view on hosts that support MCP Apps.
ask_opzero_assistantread only| Parameter | Type | Description |
|---|---|---|
| questionreq | string | Question to ask (e.g., 'What deployments are in progress?', 'Is my preview ready?', 'How many projects do I have?') |
| include_context | boolean | Include system context (projects, deployments, previews) automatically (default: true) |
diagnose_authread onlyYour token type, identity, roles, scopes, real session expiry, and the health of every OAuth discovery endpoint. Run this first on any auth error.
diagnose_authread onlyTakes no parameters.
link_identityProve your MCP client identity and your OpZero account are the same person. Returns a link URL to confirm in the browser. Required before a gateway backend may use an external connection.
link_identityTakes no parameters.
Publishing pages and apps
Getting something live. The four deploy tools differ in how much you write: markdown is the least, files is the most control.
deploy_markdownSend raw markdown, get a themed page. Full GitHub-flavoured markdown, light/dark toggle, title lifted from the first heading. The lowest-effort way to publish.
deploy_markdown| Parameter | Type | Description |
|---|---|---|
| markdownreq | string | Raw markdown content. Supports GitHub Flavored Markdown: headings, bold, italic, links, images, code blocks, tables, task lists, strikethrough, blockquotes. |
| title | string | Page title (auto-extracted from first heading if not provided) |
| theme | dark | light | auto | Color theme: auto (system preference, default), dark, or light |
| name | string | Site name for the URL (auto-generated if not provided) |
| target | cloudflare | netlify | vercel | Hosting provider: cloudflare (fastest, default), netlify, or vercel |
| force_new | boolean | When false (default), reuses an existing project with the same name and redeploys to it. Set true to always create a fresh project. |
deploy_themedSend body HTML, get it wrapped in the OpZero design system — glass nav, typography, colour palette. Standard HTML elements are styled for you.
deploy_themed| Parameter | Type | Description |
|---|---|---|
| title | string | Page title (shown in nav and browser tab) |
| contentreq | string | HTML content for the page body. Use OpZero CSS classes: oz-card (card container), oz-grid (auto grid), oz-btn-primary (cyan button), oz-btn-secondary (outline button), oz-gradient (gradient text), oz-hero (centered hero section), oz-glow (glow effect), oz-status (live indicator). Standard HTML (h1-h6, p, ul, table, pre/code, blockquote) is styled automatically. |
| theme | dark | light | auto | Color theme: auto (system preference, default), dark, or light |
| name | string | Site name for the URL (auto-generated if not provided) |
| style | landing | article | dashboard | Layout: article (800px centered, default), landing (hero-focused), dashboard (1200px wide) |
| target | cloudflare | netlify | vercel | Hosting provider: cloudflare (fastest, default), netlify, or vercel |
| force_new | boolean | When false (default), reuses an existing project with the same name and redeploys to it. Set true to always create a fresh project. |
deploy_htmlDeploy one complete HTML document. Tailwind utility classes are compiled automatically, so no CDN script or config is needed.
deploy_html| Parameter | Type | Description |
|---|---|---|
| htmlreq | string | HTML content to deploy (can include inline CSS/JS). Tailwind utility classes are auto-compiled — no CDN script needed. |
| name | string | Optional site name (auto-generated if not provided) |
| target | cloudflare | netlify | vercel | Hosting provider: cloudflare (fastest, default), netlify, or vercel |
| force_new | boolean | When false (default), reuses an existing project with the same name and redeploys to it. Set true to always create a fresh project. |
deploy_filesDeploy a multi-file site — HTML, CSS, JS, assets — with full file-level control. Tailwind is still compiled for you.
deploy_files| Parameter | Type | Description |
|---|---|---|
| projectId | string | Existing project ID to deploy to (optional - creates new if not provided) |
| name | string | Project name (auto-generated if not provided) |
| target | cloudflare | netlify | vercel | Hosting provider: cloudflare (fastest, default), netlify, or vercel |
| filesreq | object<string, string> | Object mapping file paths to contents. Tailwind utility classes in HTML files are auto-compiled. Example: {'index.html': '<html>...</html>', 'styles.css': '...'} |
| force_new | boolean | When false (default), reuses an existing project with the same name and redeploys to it. Set true to always create a fresh project. |
deploy_react_artifactDeploy a React component as a live site with zero build, via ESM.sh. React, Recharts, and Lucide are built in. Set ai and storage to turn it into a real application with a backend.
deploy_react_artifact| Parameter | Type | Description |
|---|---|---|
| codereq | string | React component code (JSX/TSX). Can use imports from react, recharts, lucide-react. Should export a default component. May call window.claude.complete(prompt) and window.storage when ai/storage are enabled. |
| name | string | Site name (auto-generated if not provided) |
| title | string | Page title (optional, defaults to 'React App') |
| dependencies | object<string, string> | Additional ESM.sh dependencies to include in import map. Format: { 'package-name': 'version' } |
| target | cloudflare | netlify | vercel | Hosting provider: cloudflare (fastest, default), netlify, or vercel. Must be cloudflare when ai/storage are enabled. |
| ai | boolean | Enable server-side AI: window.claude.complete / oz.ai stream through the Vercel AI Gateway (Haiku/GPT-mini default allowlist, owner-funded, hard-capped). Default false (plain static artifact). |
| storage | boolean | Enable persistence: window.storage / oz.storage give per-user (and shared) key-value storage, and oz.files / window.files give per-user file storage (bytes with a media type under a path, 3MB each) on the same store. Default false. |
| system_prompt | string | Pinned system prompt for the AI binding, set server-side; the client cannot override it. Optional. |
| force_new | boolean | When false (default), reuses an existing project with the same name and redeploys to it. Set true to always create a fresh project. |
get_templateread onlyReady-to-deploy starter files: the branded opzero theme (recommended), landing, portfolio, blog, static, vite-react, or react-esm.
get_templateread only| Parameter | Type | Description |
|---|---|---|
| templatereq | landing | portfolio | blog | static | vite-react | react-esm | opzero | Template type: opzero (branded theme with light/dark mode — RECOMMENDED), landing (marketing page), portfolio (personal site), blog (article site), static (basic HTML), vite-react (React app with Vite), react-esm (zero-build React via ESM.sh) |
update_deploymentPatch a live site by merging a partial file map into its latest deployment. Unmentioned files are preserved; an empty string deletes one.
update_deployment| Parameter | Type | Description |
|---|---|---|
| project_name | string | Project name to update |
| project_id | string | Project UUID to update (alternative to project_name) |
| filesreq | object<string, string> | Partial file map to merge. Keys are file paths, values are new contents. These overwrite matching files; unmentioned files are preserved. Set a value to empty string to delete a file. |
preview_pageread onlyRender one of your deployed pages inline in the conversation, on hosts that support MCP Apps. Identify it by URL, project ID, or project name.
preview_pageread only| Parameter | Type | Description |
|---|---|---|
| url | string | HTTPS URL of a page on opzero.sh (e.g. https://my-site.opzero.sh). Provide exactly one of url, project_id, or project_name. |
| project_id | string | Project UUID — its deployed URL is looked up automatically. Use this to disambiguate when several projects share a name. |
| project_name | string | Name of one of your projects — its deployed URL is looked up automatically. Errors if the name is ambiguous; use project_id then. |
live_canvasAn interactive widget showing your live site next to a prompt box. Edits typed there arrive back in the conversation, and the page hot-reloads once you apply them.
live_canvas| Parameter | Type | Description |
|---|---|---|
| html | string | HTML to deploy as the initial canvas content. Tailwind utility classes are auto-compiled. Provide exactly one of html, project_id, or project_name. |
| name | string | Optional project name when deploying html (reuses an existing project with the same name, else auto-generated). |
| project_id | string | Attach the canvas to this existing project (UUID). |
| project_name | string | Attach the canvas to the existing project with this name. Errors if ambiguous; use project_id then. |
Projects and domains
Managing the containers your deployments live in.
list_projectsread onlyEverything you have deployed, with URLs and status. Filter by status, hosting target, name, or staleness.
list_projectsread only| Parameter | Type | Description |
|---|---|---|
| status | active | archived | deleted | all | Filter by project status (default: active) |
| target | cloudflare | netlify | vercel | Filter by hosting provider |
| name_contains | string | Search projects by name (case-insensitive partial match) |
| sort_by | created | last_deploy | name | Sort order (default: last_deploy) |
| stale_days | number | Only show projects with no deploy in this many days |
| limit | number | Max results to return (default: 50, max: 100) |
get_project_detailsread onlyOne project by name or ID: metadata, current URLs, custom domain, status, and a summary of its latest deployment.
get_project_detailsread only| Parameter | Type | Description |
|---|---|---|
| name | string | Project name to look up |
| project_id | string | Project UUID to look up |
create_projectCreate an empty project container. Usually unnecessary — the deploy tools create one for you.
create_project| Parameter | Type | Description |
|---|---|---|
| namereq | string | Project name |
| description | string | What this project is about |
| target | cloudflare | netlify | vercel | Hosting provider (default: cloudflare) |
rename_projectChange a project name without touching its contents or deployment history.
rename_project| Parameter | Type | Description |
|---|---|---|
| name | string | Current project name (alternative to project_id) |
| project_id | string | Project UUID to rename |
| new_namereq | string | New project name |
project_archivedestructiveHide a project from default listings without deleting it. Reversible with the unarchive action.
project_archivedestructive| Parameter | Type | Description |
|---|---|---|
| name | string | Project name to archive/unarchive |
| project_id | string | Project UUID to archive/unarchive |
| names | string[] | Array of project names to bulk archive/unarchive (max 10) |
| action | archive | unarchive | Whether to archive or unarchive. Default: archive. Note that "archive" deletes a hosted MCP server's Worker and "unarchive" does not recreate it. |
project_cleanupread onlyAudit your account for duplicates, stale projects, and throwaway test deploys. Recommends, never deletes.
project_cleanupread onlyTakes no parameters.
project_deletedestructiveTake a project offline. Soft by default, with a seven-day window in which redeploying the name restores it; hard delete is immediate and permanent.
project_deletedestructive| Parameter | Type | Description |
|---|---|---|
| name | string | Project name to delete |
| project_id | string | Project UUID to delete |
| names | string[] | Array of project names to bulk delete (max 10) |
| hard | boolean | Permanently delete now (record + deployments) with no grace period. The live runtime is taken offline in both modes. Default false. |
set_custom_domaindestructivePoint your own domain at a project, or remove the current one. Requires Pro or Team, plus a CNAME record you add at your registrar.
set_custom_domaindestructive| Parameter | Type | Description |
|---|---|---|
| project_id | string | Project UUID to change the domain for (from list_projects) |
| name | string | Project name (alternative to project_id, from list_projects) |
| domain | string | Custom domain to set (e.g. "example.com" or "app.example.com"). Do not include protocol, path, or port. Mutually exclusive with `remove`. |
| remove | boolean | Set true to remove the project's current custom domain. This takes the site off that domain. Mutually exclusive with `domain`. |
Deployment history
Inspecting what shipped, and moving between versions.
list_deploymentsread onlyRecent deployments across all projects, or scoped to one.
list_deploymentsread only| Parameter | Type | Description |
|---|---|---|
| projectId | string | Filter by project (optional) |
| limit | number | How many to return (default: 10) |
get_deployment_detailsread onlyEverything about one deployment, including the full deployed file contents — the way to recover source a conversation has lost.
get_deployment_detailsread only| Parameter | Type | Description |
|---|---|---|
| deploymentIdreq | string | The deployment ID to inspect |
get_deployment_statusread onlyStatus, status detail, URL, file count, and size for a deployment, or the last five for a project.
get_deployment_statusread only| Parameter | Type | Description |
|---|---|---|
| deployment_id | string | Specific deployment ID to get details for |
| project_name | string | Project name to get the last 5 deployments for |
redeployRebuild a project from its stored source. MCP server projects go through the full pipeline again, preserving auth mode and runtime.
redeploy| Parameter | Type | Description |
|---|---|---|
| name | string | Project name to redeploy |
| project_id | string | Project UUID to redeploy |
| deployment_id | string | Optional: specific deployment ID to redeploy from (defaults to latest) |
rollback_deploymentRepublish an older deployment’s files as a new deployment. Forward-only, so nothing is destroyed.
rollback_deployment| Parameter | Type | Description |
|---|---|---|
| deployment_idreq | string | The deployment ID to rollback to |
delete_deployment_recorddestructivePermanently remove one deployment record from history.
delete_deployment_recorddestructive| Parameter | Type | Description |
|---|---|---|
| deployment_idreq | string | The deployment ID to delete |
App runtime and file storage
The backend your deployed apps get for free — server-side inference, key-value records, and file storage you can also reach from the conversation.
configure_bindingsTurn AI or storage on or off for a running app without redeploying its code. Also where you change the pinned system prompt, widen the model allowlist, or adjust caps. Live within about a minute.
configure_bindings| Parameter | Type | Description |
|---|---|---|
| project_idreq | string | Project ID (from list_projects or a deploy response) |
| ai | object | AI binding settings; omitted fields keep their current values |
| storage | object | Storage binding settings. Gates both oz.storage (key/value records) and oz.files (file storage) — they are two halves of one binding. |
| inject_sdk | boolean | Serve the oz.js SDK for this app (default true when any binding is enabled) |
storage_list_filesread onlyList a project’s stored files. Metadata only, never content. Defaults to the shared scope; pass a user ID for one end user’s files.
storage_list_filesread only| Parameter | Type | Description |
|---|---|---|
| project_id | string | Project ID (from list_projects or a deploy response). Pass this or project. |
| project | string | Project name, if you do not have the id. |
| prefix | string | Only list paths starting with this prefix, e.g. "reports/". Case-sensitive. |
| user_id | string | Address one end user's personal scope instead of the project-wide shared scope. |
| after | string | Resume after this path (pass the previous page's cursor). |
| limit | number | Page size. Default 200, max 1000. |
| reverse | boolean | Scan in descending path order. |
storage_read_fileread onlyRead one file. Text by default, base64 for binary, or metadata only. Files over 256KB come back as metadata rather than inlined.
storage_read_fileread only| Parameter | Type | Description |
|---|---|---|
| project_id | string | Project ID. Pass this or project. |
| project | string | Project name, if you do not have the id. |
| pathreq | string | File path, e.g. "reports/q1.csv". |
| user_id | string | Read from one end user's personal scope instead of the shared scope. |
| encoding | text | base64 | none | How to return the content. Default 'text'. |
storage_write_fileWrite a file (3MB max) where the app and its MCP servers can read it. Publish it at a credential-free URL with public.
storage_write_file| Parameter | Type | Description |
|---|---|---|
| project_id | string | Project ID. Pass this or project. |
| project | string | Project name, if you do not have the id. |
| pathreq | string | File path, e.g. "reports/q1.csv". Printable ASCII only (transliterate non-ASCII names and put the display name in metadata). Slashes allowed; no "..", leading/trailing slash, whitespace, or % ? # < > | * characters. |
| content | string | Text content, stored as UTF-8. Pass exactly one of content or content_base64. |
| content_base64 | string | Base64-encoded bytes, for binary files. Pass exactly one of content or content_base64. |
| content_type | string | Media type to store and serve. Defaults to a guess from the path extension. |
| public | boolean | Publish at a credential-free URL. Writes to the shared scope; cannot be combined with user_id. |
| user_id | string | Write into one end user's personal scope instead of the shared scope. |
| metadata | object | Arbitrary JSON kept alongside the file (max 4KB serialized). |
storage_delete_filedestructiveDelete a file, and with it any public URL it was served from.
storage_delete_filedestructive| Parameter | Type | Description |
|---|---|---|
| project_id | string | Project ID. Pass this or project. |
| project | string | Project name, if you do not have the id. |
| pathreq | string | File path to delete. |
| user_id | string | Delete from one end user's personal scope instead of the shared scope. |
Assistants
Your own agent — model, pinned instructions, and tool backends — behind a chat endpoint.
deploy_assistantCreate an assistant from a model, a system prompt, and connections to MCP servers that already exist. Served from one of your app subdomains via oz.assistant(slug).
deploy_assistant| Parameter | Type | Description |
|---|---|---|
| namereq | string | Human-readable name for the assistant (e.g. "Support Bot") |
| slug | string | URL-safe identifier (lowercase, hyphens). Auto-generated from name if not provided. Used in oz.assistant(slug) and the /__oz/assistant/<slug>/chat endpoint. |
| model | string | Vercel AI Gateway model ID (default: anthropic/claude-haiku-4.5). Any gateway model works: anthropic/claude-sonnet-4, openai/gpt-4o, etc. |
| system_prompt | string | System prompt that defines the assistant's behavior. Pinned server-side — clients cannot override it. |
| mcp_servers | object[] | MCP servers the assistant connects to and calls as tools — points at servers that ALREADY EXIST (one of OpZero's own mcps/* services, or any Streamable HTTP MCP server you already host elsewhere). This does not deploy or create a new MCP server for you; there is no deploy_* tool that turns arbitrary code into an MCP server. Each connected server's tools are discovered at request time and made available to the model. |
| max_tokens | number | Max output tokens per response (default: 2048) |
| max_steps | number | Max tool-use rounds per request (default: 8, max: 20). Higher values let the assistant chain more tool calls. |
| rate_limit_per_minute | number | Per-IP rate limit (default: 30 requests/minute) |
list_assistantsread onlyYour assistants with their slugs, models, connected servers, and status.
list_assistantsread only| Parameter | Type | Description |
|---|---|---|
| status | active | archived | all | Filter by status (default: active) |
| limit | number | Max results (default: 50, max: 100) |
get_assistantread onlyOne assistant’s full config and its chat endpoint URL.
get_assistantread only| Parameter | Type | Description |
|---|---|---|
| slug | string | Assistant slug |
| assistant_id | string | Assistant UUID |
update_assistantChange the model, prompt, connected servers, or limits. Effective immediately, no redeploy.
update_assistant| Parameter | Type | Description |
|---|---|---|
| slug | string | Assistant slug to update |
| assistant_id | string | Assistant UUID to update |
| name | string | Updated name |
| model | string | Updated model ID |
| system_prompt | string | Updated system prompt |
| mcp_servers | object[] | Updated list of already-running MCP servers to connect to (replaces the full list). Points at existing Streamable HTTP servers, same as in deploy_assistant — does not create or deploy a new one. |
| max_tokens | number | Updated max output tokens |
| max_steps | number | Updated max tool-use rounds |
| rate_limit_per_minute | number | Updated rate limit |
delete_assistantdestructiveDelete an assistant. Its chat endpoint stops responding at once.
delete_assistantdestructive| Parameter | Type | Description |
|---|---|---|
| slug | string | Assistant slug to delete |
| assistant_id | string | Assistant UUID to delete |
chat_with_assistantTalk to one of your assistants server-side — the way to test one before any app exists. Returns the whole reply plus a trace of each tool-use round.
chat_with_assistant| Parameter | Type | Description |
|---|---|---|
| slugreq | string | Slug of one of your deployed assistants (see list_assistants). Must be active. |
| prompt | string | Single-turn shorthand: one user message. Provide either prompt or messages. |
| messages | object[] | Conversation to send, oldest first (max 100). The assistant keeps no history of its own, so replay every turn it should see. Provide either messages or prompt. |
Hosted MCP servers
Write a server, hand it to OpZero, get a live endpoint that is verified to speak MCP.
get_mcp_server_templateread onlyA known-good scaffold to build from: minimal, fetch-api, oauth1-api, storage, files, widget, sync, or python. Start here rather than from scratch.
get_mcp_server_templateread only| Parameter | Type | Description |
|---|---|---|
| kind | minimal | fetch-api | oauth1-api | storage | files | widget | sync | python | Template kind. Default minimal. storage demonstrates ctx.user + per-user ctx.storage; files demonstrates per-user ctx.files (byte content under paths) plus publishing to a credential-free public URL; widget demonstrates an MCP Apps view authored as its own .html file and linked to tools; sync demonstrates a scheduled() handler on a cron, a plain-HTTP ingest tool, and ranged value queries for rollups; python is the minimal server authored in Python against the opzero_mcp runtime. |
deploy_mcp_serverBuild and deploy TypeScript or Python source as a hosted MCP server on a stable endpoint, with your chosen auth mode and an optional cron schedule.
deploy_mcp_server| Parameter | Type | Description |
|---|---|---|
| name | string | Project name for the MCP server. |
| filesreq | object<string, string> | Source files keyed by path. TypeScript: include server.ts, index.ts, server.js, index.js, main.ts, or main.js; only @opzero/mcp-runtime and zod may be imported; files ending in .html, .css, .svg, .txt, or .md bundle as importable strings (import html from './view.html') — author MCP Apps widget views as .html files and pass the import to widget({ html }). Python: include server.py, index.py, or main.py with a module-level server = define_server(...) from opzero_mcp; only the Python standard library, opzero_mcp, workers, js, and pyodide may be imported (get_mcp_server_template kind "python" shows the shape). |
| runtime | cloudflare | vercel | Runtime target. Default cloudflare. Vercel requires account entitlement. |
| auth_mode | token | public | oauth | token requires a shared Bearer token, public is unauthenticated, oauth validates per-user tokens through OpZero's authorization server and scopes access to you (the deployer) with audience-bound tokens so other users cannot call your server. |
| secrets | object<string, string> | Environment secrets exposed as ctx.env.KEY and stored encrypted. |
| project_id | string | Existing MCP server project ID to redeploy into. |
| force_new | boolean | Create a fresh project even if a matching name exists. |
| allow_public_shared_storage | boolean | public auth_mode only: allow ctx.storage shared-scope operations (off by default because any anonymous caller could mutate shared state). |
| schedule | string | Cron expression (UTC, 5 fields, or @hourly/@daily/@weekly/@monthly) that runs the server's exported scheduled() handler — a deployed server cannot wake itself, so this is how sync/rollup servers run unattended. Minimum interval is 5 minutes (the scheduler tick). Omit to keep the current schedule on redeploy; pass an empty string to remove it. |
get_mcp_server_logsread onlyDeployment health, recent deploy records, and a live Cloudflare tail when one is available. The first stop when a server misbehaves.
get_mcp_server_logsread only| Parameter | Type | Description |
|---|---|---|
| project_id | string | MCP server project UUID. Provide this or project_name. |
| project_name | string | MCP server project name. Provide this or project_id. |
| limit | integer | Recent deployment record count. Default 10. |
| since | string | ISO timestamp lower bound for deployment records. |
list_mcp_app_widgetsread onlyWhich MCP Apps widgets your server exposes and which tools render into each — including tools pointing at a widget that does not exist.
list_mcp_app_widgetsread only| Parameter | Type | Description |
|---|---|---|
| project_id | string | MCP server project UUID. Provide this or project_name. |
| project_name | string | MCP server project name. Provide this or project_id. |
set_mcp_server_secretSet an encrypted environment secret, exposed to the server as ctx.env.KEY. Cloudflare picks it up immediately.
set_mcp_server_secret| Parameter | Type | Description |
|---|---|---|
| project_idreq | string | The MCP server project ID. |
| keyreq | string | Environment variable name. |
| valuereq | string | Secret value. It is write-only and never returned. |
list_mcp_server_secretsread onlyThe secret keys configured on a server. Values are never returned.
list_mcp_server_secretsread only| Parameter | Type | Description |
|---|---|---|
| project_idreq | string | The MCP server project ID. |
delete_mcp_server_secretdestructiveRemove an environment secret.
delete_mcp_server_secretdestructive| Parameter | Type | Description |
|---|---|---|
| project_idreq | string | The MCP server project ID. |
| keyreq | string | Secret key to delete. |
rotate_mcp_server_tokendestructiveReplace a token-mode server’s access token. The old one stops working immediately; the new one is shown exactly once.
rotate_mcp_server_tokendestructive| Parameter | Type | Description |
|---|---|---|
| project_idreq | string | The MCP server project ID. |
Gateways
One MCP endpoint fronting many backends, behind an exposure policy.
create_gatewayA federated endpoint at gw.opzero.sh/g/<slug>/mcp. Choose the exposure mode carefully — search is right for Claude.ai.
create_gateway| Parameter | Type | Description |
|---|---|---|
| namereq | string | Human-readable name for the gateway (e.g. "Support Bot Tools") |
| slug | string | URL-safe identifier (lowercase, hyphens). Auto-generated from name if not provided. The gateway endpoint is gw.opzero.sh/g/<slug>/mcp. "default" is reserved. |
| description | string | What this gateway is for |
| exposure_mode | auto | inline | search | pinned | How tools are exposed. search (recommended, and required for clients that snapshot tools/list like Claude.ai): a constant three-tool surface (search_tools, invoke_read_tool for backend tools explicitly marked read-only, invoke_write_tool for everything else) whose shape never changes, with live discovery at call time. inline (all tools merged into tools/list, namespaced <ns>_<tool>): only for clients that re-list every session (Claude Code, API mcp_servers) with small fixed toolsets — the surface changes whenever backends do, which strands snapshot caches. pinned: chosen tools inline + meta-tools for the rest. auto: resolves to search whenever track_all_deployed is true (open-ended tool population must not flip surface shape mid-lifecycle); otherwise inline until the tool count exceeds inline_tool_limit, then search. Default: auto. |
| inline_tool_limit | number | Tool-count threshold where auto mode flips from inline to search (default 40) |
| track_all_deployed | boolean | When true, every active deployed MCP server is federated automatically without explicit backend rows (default false; the default gateway has this on) |
list_gatewaysread onlyYour gateways with endpoints and backend counts. Materializes the default gateway on first call.
list_gatewaysread only| Parameter | Type | Description |
|---|---|---|
| limit | number | Max gateways to return (default 50) |
get_gatewayread onlyOne gateway in full: exposure policy, backend attachments with namespaces, and per-backend health.
get_gatewayread only| Parameter | Type | Description |
|---|---|---|
| slug | string | Gateway slug |
| gateway_id | string | Gateway UUID (alternative to slug) |
update_gatewayChange the name, exposure mode, inline limit, pinned tools, or tracking flag. Live within about thirty seconds.
update_gateway| Parameter | Type | Description |
|---|---|---|
| slug | string | Gateway slug |
| gateway_id | string | Gateway UUID (alternative to slug) |
| name | string | New name |
| description | string | New description |
| exposure_mode | auto | inline | search | pinned | New exposure mode. search is recommended for any gateway consumed by Claude.ai (constant three-tool surface immune to tools/list snapshot caching); inline suits only re-listing clients with small fixed toolsets; auto resolves to search whenever track_all_deployed is true. |
| inline_tool_limit | number | New auto-mode threshold |
| pinned_tools | string[] | Qualified tool names (<namespace>_<tool>) shown inline in pinned mode |
| track_all_deployed | boolean | Automatically federate all deployed MCP servers |
add_gateway_backendAttach a hosted server, an external MCP server, or an assistant, under a namespace that prefixes its tool names. Use an external connection for third-party credentials.
add_gateway_backend| Parameter | Type | Description |
|---|---|---|
| gateway_slug | string | Gateway to attach to (or use gateway_id) |
| gateway_id | string | Gateway UUID (alternative to gateway_slug) |
| typereq | opzero_mcp | external_mcp | assistant | Backend type |
| namespacereq | string | Tool-name prefix, unique per gateway (lowercase alphanumeric + underscores, e.g. "shop") |
| server_id | string | opzero_mcp: the project id (UUID from list_projects) or the mcp_server id (from get_project_details). Both resolve to the project's current MCP endpoint. |
| assistant_slug | string | assistant: the assistant slug |
| assistant_id | string | assistant: the assistant UUID (alternative to assistant_slug) |
| url | string | external_mcp: the Streamable HTTP MCP endpoint URL. Optional when connection is given (the connection supplies its own server url); pass it anyway to point a connection at a self-hosted instance of the same service. |
| connection | string | external_mcp only: use one of your external connections (create_connection) as this backend's credential. Accepts the connection label, the provider slug, or the connection id from list_connections. The gateway fetches a fresh access token per call and refreshes it automatically, so this is the right choice for any OAuth service. Attaching also grants this backend access to the connection; remove_gateway_backend revokes that grant. Requires your MCP identity to be linked (link_identity) - external connections are never released to an identity matched only by an unverified email. Mutually exclusive with auth_bearer and use_caller_token. |
| auth_bearer | string | external_mcp only: bearer token the gateway sends to this backend. Stored encrypted; never returned. Mutually exclusive with use_caller_token. |
| use_caller_token | boolean | external_mcp only: forward each caller's own OpZero bearer token to the backend instead of a stored credential, so the backend sees the caller as themselves. Only allowed for OpZero service-owned endpoints (currently https://code.opzero.sh) — never tenant app subdomains or hosted MCP hosts, which run user-controlled code; the token is never sent anywhere else. Mutually exclusive with auth_bearer. Example: federate your CodeZ Hub machines through a gateway with url "https://code.opzero.sh/mcp", namespace "hub", use_caller_token true. |
| tool_allowlist | string[] | Backend-local tool names to expose (omit for all tools) |
| position | number | Sort order in listings (default 0) |
remove_gateway_backenddestructiveDetach a backend. The backend itself survives; any connection grant it held through this gateway is revoked.
remove_gateway_backenddestructive| Parameter | Type | Description |
|---|---|---|
| backend_idreq | string | The gateway backend attachment UUID |
delete_gatewaydestructiveDelete a gateway and its attachments. Backends are untouched. The default gateway cannot be deleted.
delete_gatewaydestructive| Parameter | Type | Description |
|---|---|---|
| slug | string | Gateway slug |
| gateway_id | string | Gateway UUID (alternative to slug) |
External connections
OAuth grants to third-party MCP servers, stored encrypted and released only to workloads you name.
create_connectionConnect Notion, Linear, Sentry, Neon, Vercel, or any RFC 9728 server. Returns a one-time authorize URL; the grant is stored encrypted and refreshed for you.
create_connection| Parameter | Type | Description |
|---|---|---|
| provider | string | Catalog provider slug (notion, linear, sentry, neon, vercel). Omit when passing an explicit url. |
| url | string | Streamable HTTP MCP endpoint of any external server. Required for servers not in the catalog; also overrides a catalog entry so you can point at a self-hosted instance. The server must publish RFC 9728 protected resource metadata. |
| label | string | Name for this connection, e.g. "Work Notion". Defaults to the provider name. Lets you hold several accounts with the same provider. |
| grant_to_kind | gateway_backend | assistant | mcp_server | Optionally attach the resulting connection to a workload in the same step (otherwise use grant_connection later). Connections are never ambient: nothing can use one until it is granted. |
| grant_to_id | string | Id of the workload to grant. Required with grant_to_kind. |
list_connectionsread onlyYour connections with status, granted scope, and which workloads may use each. Status needs_reauth means the grant must be recreated.
list_connectionsread only| Parameter | Type | Description |
|---|---|---|
| limit | number | Max connections to return (default 50) |
grant_connectionLet one workload use one connection, or revoke that permission. This is the consent boundary — nothing is ambient.
grant_connection| Parameter | Type | Description |
|---|---|---|
| connection_idreq | string | Connection UUID from list_connections |
| subject_kindreq | gateway_backend | assistant | mcp_server | What kind of workload is being granted access |
| subject_idreq | string | Id of the workload: gateway backend id (get_gateway), assistant id (list_assistants), or mcp_server id (get_project_details) |
| note | string | Optional note recording why this grant exists |
| revoke | boolean | Remove the grant instead of creating it |
delete_connectiondestructiveRevoke at the provider where supported, delete the stored credential, and drop every grant on it.
delete_connectiondestructive| Parameter | Type | Description |
|---|---|---|
| connection_idreq | string | Connection UUID from list_connections |