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:

• ?toolset=core — advertises ~40 golden-path tools plus the oxygen_capabilities_search / oxygen_capabilities_schema discovery pair, instead of the several hundred in the full registry. Use it for clients without tool search, where a large inline tool list crowds the context window. Hidden tools remain callable by exact name and are one oxygen_capabilities_search away. ?toolset=full (the default) advertises everything.
• ?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.

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, and in_core. A non-empty ranked list confirms the connector is live even when the tool you want is not in the advertised list.

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.
• Clients without tool search should request ?toolset=core — the full registry can exceed a small context budget. 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.