oz0 plugin import openapi
For: Operators and developers looking up a command.
Read an OpenAPI 3.0 or 3.1 document (YAML or JSON, a file or an https:// URL, which is fetched once, at most 16 MiB) and write an ordinary plugin into --out: an MCP server of fixed code from Orchestrator Zero's template and the document's operations as data (src/<module>/operations.json).
Each operation becomes a function of the plugin's one tool, named after its operationId (or its method and path) in snake case; two operations that come to one name are refused, naming both. Its arguments are the path, query and header parameters and the request body as body, with $ref resolved (a recursive one cut where it comes back) and oneOf, allOf and formats kept; its output is the HTTP status and the JSON body, not checked against the document.
GET, HEAD and OPTIONS are marked read-only, DELETE destructive and the rest as writes, every one as reaching an outside API; every write (POST, PUT, PATCH, DELETE) asks a person by default through the plugin's suggested policy (policy:), decided by an operator who did not start the job, which the installer may switch with a reason (--writes-without-approval leaves them to the tenant's tool policy).
The server calls only the base URL's host (the document's first server, or --base-url), which is also the plugin's egress; it encodes every argument into its place and follows no redirect to another host. The credential (--auth, else the document's security scheme) is a tenant secret the node's egress proxy puts on the requests, so the plugin's process holds only a placeholder; --auth-secret gives the process the value instead, for nodes that cannot inject.
With --connection, an API on each tenant's own instance (a Jira, a GitLab) has no URL or secret fixed at import: each call gets its token and the instance's URL from that connection of the plugin, which the manifest declares with a step where an admin pastes both (replace it with the API's own sign-in where it has one), and the call goes to that instance only; --base-path sets the path under the instance's URL.
What could not be carried over is listed in the output and the plugin's README. Then: uv lock, plugin lint, plugin install.
Usage
oz0 plugin import openapi <file | https-url> [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--ai-label | stringArray | where a function that writes what people read puts the tenant's AI label: <function>=<JSON pointer into its arguments>, such as add_comment=/body/body (repeatable) | |
--allow-http | bool | allow an http:// base URL, for a local test API without a credential | |
--auth | string | the document's security scheme | how the API takes its credential: bearer, header:NAME, basic:USER, query:NAME or none |
--auth-secret | bool | give the plugin's process the secret's value instead of binding it to the API's host for the node's egress proxy to inject | |
--base-path | string | the document's first server's path; / for none | with --connection: the path under the instance's URL that the operations are under |
--base-url | string | the API's base URL, instead of the document's first server (https://) | |
--connection | string | the plugin's connection that gives each call its token and the API's URL (an instance of the tenant's own), instead of a tenant secret and a URL fixed at import | |
--force | bool | rewrite a folder an earlier import wrote, keeping files it does not write (such as uv.lock) | |
--json | bool | print what was written as JSON | |
--name | string | the plugin's name (lowercase letters, digits and dashes); its tool ID is the name with _ for - | |
--operations | stringArray | import only operations whose function name, operationId or "METHOD /path" matches this glob; * stops at /, so 'GET /invoices/*' matches GET /invoices/{id} but not GET /invoices (repeatable) | |
--out | string | the folder to write the plugin into; it must be empty or not exist (see --force) | |
--quiet-budget | bool | do not explain a result over the tool-size budget (the token count is still printed) | |
--rename | stringArray | give a function a name of its own: <operationId or "METHOD /path">=<name>, such as search_1=search_issues (repeatable) | |
--secret | string | <NAME>_API_KEY | the tenant secret that holds the credential |
--tag | stringArray | import only operations with this tag (repeatable) | |
--writes-without-approval | bool | leave the writes (POST, PUT, PATCH, DELETE) to the tenant's tool policy instead of having each ask a person by default |
Inherited flags
| Flag | Type | Default | Description |
|---|---|---|---|
--context | string | $OZ0_CONTEXT or <config dir>/orchestrator-zero/context.json | CLI context file written by server init |
--log-level | string | info | log level: debug, info, warn or error |
See all oz0 commands and the global flags.