Generic MCP client

Any MCP-capable client can operate Oxygen through the hosted MCP server. If your client also has a terminal, the oxygen CLI is available too.

What works here

Endpoint

https://oxygen-agent.com/mcp

The server speaks Streamable HTTP and publishes OAuth discovery metadata (RFC 9728 protected-resource metadata and RFC 8414 authorization-server metadata). Unauthenticated requests get a 401 with a WWW-Authenticate challenge pointing at the resource metadata.

Setup — OAuth (recommended)

Add the endpoint as a custom/remote MCP connector. On first use the client registers itself through dynamic client registration and opens the OAuth sign-in. After sign-in, call oxygen_whoami; if the account has more than one organization, call oxygen_orgs_select with the org slug.

Setup — bearer token

For clients that cannot complete an OAuth flow, mint a CLI API key and configure the client to send it as an Authorization: Bearer <token> header:

oxygen api-keys create --name "mcp client" --json

Store the token in the client's credential or connector configuration. Do not paste it into prompts or documents.

Toolset and widget parameters

Two query parameters shape the connection:

• No toolset parameter, or ?toolset=core — advertises the bounded golden-path tools plus the oxygen_capabilities_search / oxygen_capabilities_schema discovery pair. A bare URL means core; it does not restore the former full list.
• ?toolset=<pack> — adds one or more focused domain packs on top of core, such as ?toolset=crm,sequences. Capability results return toolset_pack, the smallest pack that advertises a selected tool. Every pack and its tools: MCP tool reference.
• ?toolset=full — explicitly advertises every customer tool. Use it when an existing automation genuinely spans the registry and the host refuses tools omitted from tools/list.
• ?widgets=off|inline — forces the inline widget HTML block off or on, overriding client detection. See Widgets.

An unrecognized toolset token is ignored rather than rejected, so a typo silently falls back to core instead of blanking the tool list. full anywhere in the list wins.

The Oxygen server accepts an exact hidden tool name regardless of the advertised profile. Some hosts enforce their own tools/list first and reject that name client-side. If the client reports No such tool available, reconnect with the result's ?toolset=<toolset_pack>; for Claude Cowork, follow the dedicated Cowork setup and recovery guide.

Widgets

ui:// widgets render on MCP-Apps hosts — Claude Desktop, Claude on the web, and ChatGPT connectors. Of these, only Anthropic's connector has been observed against Oxygen's server; treat any other host as unverified until you see a widget render.

Oxygen auto-detects terminal-shaped agents (Claude Code, Codex) and strips the inline block for them. An unrecognized client — including one behind a proxy that hides its User-Agent — still receives it, so if your client does not render widgets, set ?widgets=off rather than paying for the block in context. ?widgets=inline forces it on for a rendering host Oxygen does not recognize.

Verify your setup

Ask the client to run these read-only tool calls (they spend no credits):

• oxygen_whoami — returns your user email and the active organization.name, plus an onboarding block. If onboarding.complete is false, load workspace context before paid work.
• oxygen_capabilities_search with a query like export a table to my CRM — returns ranked tool matches, each flagged read_only, paid, in_core, and toolset_pack. A non-empty ranked list confirms the connector is live; the pack tells strict clients how to advertise the selected tool.

Cost and approval posture

Read and dry-run tools (oxygen_tools_run_dry, reads) never spend credits; paid tools (oxygen_tools_run_live, oxygen_columns_run on paid columns, enrichment, external writes) run only after you approve the row scope and credit ceiling. See Approvals and Spend caps.

Known limitations

• On a client that does not render widgets, use the web_url in each result and the web app to inspect state.
• The full registry can exceed a small context budget. Prefer core or a domain pack for focused work; reserve ?toolset=full for clients or existing automations that truly need it.
• Do not stream large CSV/JSON files through an MCP prompt; use oxygen_cli_file_import_prepare, which returns a local oxygen tables import ... --background command to run where the CLI is installed.