MCP & AI agents

Oxygen runs a hosted MCP server at https://oxygen-agent.com/mcp. Claude Desktop, Claude Code, Codex, and other MCP-capable clients can use it to operate the same primitives exposed by the CLI: orgs, context, tables, columns, tools, runs, billing, integrations, and workflows.

For per-client setup and verification, see the agent-client guides: Claude Code, Claude Desktop, Codex, Cursor, and any other MCP client.

The expected flow is:

Call oxygen_whoami.
Select an organization if needed with oxygen_orgs_select.
Resolve context with oxygen_context_resolve.
Do GTM work through table, tool, column, run, workflow, or integration tools.
Use returned web_url values and ui:// widgets to inspect results.

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 in Oxygen and configure the MCP 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.

Tool naming

MCP tools use the oxygen_ prefix and mirror the CLI/API surface.

Work	MCP tools
Identity and orgs	`oxygen_whoami`, `oxygen_orgs_list`, `oxygen_orgs_select`
Context	`oxygen_context_resolve`, `oxygen_context_profile_get`, `oxygen_context_profile_update`, `oxygen_context_assets_list`
Tables	`oxygen_tables_list`, `oxygen_tables_describe`, `oxygen_tables_preview`, `oxygen_tables_query`, `oxygen_tables_create`, `oxygen_rows_upsert`
Columns and runs	`oxygen_columns_add`, `oxygen_columns_run`, `oxygen_enrich_column_preview`, `oxygen_enrich_column_run`, `oxygen_table_runs_get`, `oxygen_table_runs_items`
Tools	`oxygen_tools_search`, `oxygen_tools_get`, `oxygen_tools_run_dry`, `oxygen_tools_run_live`
Workflows	`oxygen_workflows_schema`, `oxygen_workflows_apply`, `oxygen_workflows_call`, `oxygen_workflows_runs`, `oxygen_workflows_tail`
Integrations	`oxygen_integrations_list`, `oxygen_integrations_connect`, `oxygen_integrations_list_actions`, `oxygen_integration_events_list`
Billing and observability	`oxygen_billing_balance`, `oxygen_billing_usage`, `oxygen_observability_events`

Use tools/list or oxygen_widgets_list for the complete current tool and widget list.

Workflows as MCP tools

The oxygen_workflows_* tools above are the generic workflow surface — author (oxygen_workflows_apply), run any workflow (oxygen_workflows_call), and inspect runs (oxygen_workflows_runs, oxygen_workflows_tail). You can also publish one specific workflow as its own MCP tool — the "Clay Functions" pattern — so an agent can call it by name instead of routing everything through the generic dispatcher.

Opt in per workflow. Run oxygen workflows mcp enable <workflow> (or the oxygen_workflows_mcp_enable tool). Only workflows you explicitly enable are published; oxygen workflows mcp disable <workflow> removes the tool again (the workflow itself stays active and still callable via oxygen_workflows_call).
The tool name is oxygen_workflow_<slug>. The workflow's slug is used verbatim, hyphens preserved — the lead-cleanup workflow becomes oxygen_workflow_lead-cleanup. A name over 64 characters is skipped from discovery until the slug is shortened (oxygen workflows mcp enable warns you when this happens).
Discovery is through tools/list. Published workflows appear alongside the static oxygen_* tools; oxygen workflows mcp list shows what is currently published, each with its resolved tool_name.
A bare call runs a dry run. Calling oxygen_workflow_<slug> with just its inputs previews the run without spending credits or writing externally.
Live execution is gated. To actually run it, pass mode: "live" with approved: true and a max_credits ceiling — after inspecting a dry run. This is the same approval gate oxygen_workflows_call enforces.

Widgets

Tools whose output benefits from visual inspection return ui:// widgets as well as readable text and structured JSON.

Widget	Used for
`oxygen.table-preview`	Table previews, table queries, and table descriptors
`oxygen.table-import-summary`	Row upserts and imports
`oxygen.run-timeline`	Table action runs, table ingestions, enrichment runs, and workflow runs
`oxygen.provider-summary`	Provider attempt and credit breakdowns
`oxygen.context-profile`	Workspace context readiness
`oxygen.billing-balance` / `oxygen.billing-usage`	Credit balance and usage
`oxygen.workflow-overview`	Workflow definitions
`oxygen.reviews-queue` / `oxygen.reviews-card`	Human review queues for AI-generated outreach
`oxygen.lead-sourcing-plan` / `oxygen.lead-sourcing-audit`	TAM planning and sourced-table quality checks

Widgets are inspection surfaces. The JSON result remains the source an agent should use for ids, cursors, and retry commands.

Large files

Do not send large CSV, JSON, JSONL, or XLSX files through an MCP prompt. Use the CLI handoff tool:

oxygen_cli_file_import_prepare

It returns a local oxygen tables import ... --background command so the file stays on the user's machine and the resulting ingestion run remains 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 should be called only after the user approves the scope and credit ceiling.

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.