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.

Connecting a client

For Claude Desktop, add a custom connector pointing at:

https://oxygen-agent.com/mcp

Sign in when the OAuth flow opens, then ask Claude to run oxygen_whoami and oxygen_tables_list.

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

1. oxygen_whoami.
2. oxygen_orgs_select if an organization is not already selected.
3. oxygen_context_resolve for workspace context.
4. oxygen_capabilities_search to route the outcome.
5. oxygen_capabilities_schema on only the selected names, then call the gateway tool.
6. 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_* pair. Oxygen dispatches every other customer oxygen_* tool by exact name, but some hosts — including Claude Cowork — refuse names absent from their initial tools/list before the request reaches Oxygen.

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. If the host reports No such tool available, reconnect with ?toolset=<toolset_pack>; 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

Tools whose output benefits from visual inspection return a ui:// widget alongside readable text and structured JSON. oxygen_widgets_list returns every advertised widget and the tools that render it; it sits in the workspace pack rather than core, so a host that enforces tools/list needs ?toolset=workspace. 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.