MCP & AI agents

Oxygen runs a hosted MCP server at https://oxygen-agent.com/mcp. It exposes the same primitives as the CLI, over the same /api/cli/* contract. Every tool is listed in the MCP reference, grouped by the toolset pack that advertises it.

Per-client setup and verification: Claude Code, Claude Desktop, Claude Cowork, Codex, Cursor, any other MCP client.

The ChatGPT connection uses a separate reviewed allowlist at ?toolset=chatgpt-v1. It lists named search, recurring-feed and column operations; it does not expose capability dispatch or arbitrary catalog tools. The core and domain-pack discovery flows below apply to general MCP clients.

Connecting a client

For Claude Desktop, add a custom connector pointing at:

https://oxygen-agent.com/mcp

For clients that need a bearer token, create a CLI API key and configure the client to send it as Authorization: Bearer <token>:

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

Do not paste API keys into prompts or docs. Store them in the client's credential or connector configuration.

Session flow

oxygen_whoami.
oxygen_orgs_select if an organization is not already selected. An app connected with OAuth remembers the choice as its own default workspace; the person can change each app's default in Connected apps.
oxygen_context_resolve for workspace context.
oxygen_capabilities_search to route the outcome.
oxygen_capabilities_schema on only the selected names, then call the gateway tool.
Open the returned web_url values and ui:// widgets to inspect results.

Search first, hydrate exactly

A bare URL advertises the core toolset plus the always-listed oxygen_capabilities_* tools: search, schema, and the two runners. Some hosts — including Claude Cowork and Claude Desktop — refuse to call a name absent from their tools/list, so every other customer tool runs through oxygen_capabilities_read (read-only tools; it refuses writes and credit spend) or oxygen_capabilities_call (anything else), each taking { tool, arguments }.

oxygen_capabilities_search returns an ownership card (layer, primitive, negative boundary, posture, skills, endpoint families, recommended gateways) plus bounded MCP matches. Each match carries its toolset_pack, the smallest connector profile that advertises it. Follow with oxygen_capabilities_schema for one or a few exact names, then run the tool through the matching runner. The run is the tool's own: same validation, previews, spend caps, approvals and result. ?toolset=<toolset_pack> remains available when you want a pack listed natively; use ?toolset=full only when an automation truly needs the complete advertised registry.

Provider operations use a separate path: bounded oxygen_tools_search → exact oxygen_tools_get. Public or third-party LinkedIn reads route to native cookieless scraper.* operations; linkedin.* is for the connected workspace account's private data and writes.

Workflows as MCP tools

oxygen_workflows_apply, oxygen_workflows_call, oxygen_workflows_runs, and oxygen_workflows_tail are the generic workflow surface. You can also publish one workflow as its own MCP tool — the "Clay Functions" pattern — so an agent calls it by name instead of routing through the generic dispatcher.

Opt in per workflow. oxygen workflows mcp enable <workflow> (or oxygen_workflows_mcp_enable). Only workflows you explicitly enable are published; oxygen workflows mcp disable <workflow> removes the tool again and leaves the workflow active and callable via oxygen_workflows_call.
The tool name is oxygen_workflow_<slug>. The slug is used verbatim, hyphens preserved — lead-cleanup becomes oxygen_workflow_lead-cleanup. A name over 64 characters is skipped from tools/list until the slug is shortened; oxygen workflows mcp enable warns you when that happens.
Discovery is through tools/list. Published workflows appear alongside the static oxygen_* tools; oxygen workflows mcp list shows what is currently published with each resolved tool_name.
A bare call runs a dry run. mode defaults to dry_run, which previews without spending credits or writing externally.
Live execution is gated. Pass mode: "live" with approved: true and a max_credits ceiling, after inspecting a dry run. Same gate oxygen_workflows_call enforces.

Widgets

The Table widget is the Oxygen grid itself, shown on MCP-Apps hosts such as Claude: previewing a table (oxygen_tables_preview) or a company search (oxygen_companies_search_preview) shows it beside readable text and structured JSON. Every other tool answers in text plus its deep-link. oxygen_widgets_list returns every advertised widget and the tools that render it; it sits in the workspace pack, so from core run it through oxygen_capabilities_read. Widgets are inspection surfaces — the JSON result stays the source for ids, cursors, and retry commands.

Large files

Do not send large CSV, JSON, JSONL, or XLSX files through an MCP prompt. Call oxygen_cli_file_import_prepare instead: it returns a local oxygen tables import ... --background command, so the file stays on the user's machine and the resulting ingestion run stays inspectable in Oxygen.

Safety in MCP calls

oxygen_tools_run_dry previews a tool call without spending credits. oxygen_tools_run_live, oxygen_columns_run on paid columns, enrichment runs, and external writes require the user's approved scope and credit ceiling first — see Approvals.

For bulk work, prefer table or enrichment runs over many one-off live tool calls. Runs produce timelines, failed-item lists, provider summaries, billing entries, and web deep-links.