Generic MCP client

Any MCP-capable client can operate Oxygen through the hosted MCP server. This page covers the client-agnostic contract: the endpoint, the two authentication paths, the toolset and widget parameters, and how to verify the connection. 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 that points 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.
• ?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 — controls whether tool results embed the inline widget HTML block. Terminal clients are auto-detected and suppressed by default; set ?widgets=off when connecting through a proxy that hides the real client's User-Agent, or ?widgets=inline to force the block for a host that renders inline widgets but is not recognized.

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.

Verify your setup

Ask the client to run these read-only tool calls (they do not spend 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

• Widgets render only on MCP-Apps hosts; on every other client 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. The exact tool count moves as tools ship; oxygen_capabilities_search always reflects the live registry.
• 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.