MCP & AI agents
Oxygen exposes workspace primitives as MCP tools prefixed `oxygen_*`.
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.
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_urlvalues andui://widgets to inspect results.
Connecting a client
For Claude Desktop, add a custom connector pointing at:
https://oxygen-agent.com/mcpSign 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 in Oxygen and configure the MCP client to send it as Authorization: Bearer <token>:
oxygen api-keys create --name "mcp client" --jsonDo 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.
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_prepareIt 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.