OpenAPI Tools

Omegon can turn REST APIs into agent-callable tools from OpenAPI JSON or YAML. Add a project-local .omegon/openapi.toml, restart the session, and matching operations become structured tools alongside the built-in file, memory, search, and lifecycle tools.

Configuration

[linear]
spec = "api/linear.openapi.yaml"
auth = "bearer"
secret = "LINEAR_API_KEY"
read_only = true

[internal]
spec = "https://example.com/openapi.json"
auth = "X-API-Key"
secret = "INTERNAL_API_KEY"
base_url_override = "https://staging.example.com"

Field	Behavior
`spec`	Local JSON/YAML path resolved from the project root, or an `http(s)` URL fetched at startup.
`auth`	`bearer`, `basic`, or a custom header name.
`secret`	Environment variable containing the credential value.
`base_url_override`	Optional replacement for the OpenAPI server URL.
`read_only`	When true, only `GET` operations become tools.

Generated Tools

Tools are registered in the openapi-tools group.
Tool names use api_<config-name>_<operationId>, normalized to snake case.
Operations without operationId derive a name from method and path.
Path parameters, query parameters, and JSON request-body properties become tool arguments.
GET operations are treated as inspection tools; other methods are treated as state-changing tools.
Responses are returned as text and truncated at 50 KB.

Safety

Treat OpenAPI tools like production API access. Use scoped API keys, prefer read_only = true for inspection-only integrations, and do not store raw credentials in .omegon/openapi.toml. The config parser accepts allow and confirm fields for future policy work, but current enforcement is limited to read_only.

When to Use This

Use OpenAPI tools when an existing REST API already has a spec and you want the agent to call it directly.
Use MCP when you already have an MCP server or need resources/prompts in addition to tools.
Use an extension when the integration needs custom process logic, widgets, resources, or long-running local behavior.