Codex Plugin

MarcoPolo is a data computer that connects to your databases, warehouses, cloud storage, and SaaS applications, and provides a workspace where AI can query, correlate, analyze, and act on that data. The MarcoPolo plugin is the most effective way to connect Codex to this computer — it bundles the MCP connection with skills that guide Codex through proven data workflows.

What you can do

With the plugin installed, Codex can:

• Explore and profile unfamiliar connections — navigate schemas, check data quality, map relationships, and save context to RULES.md
• Query and join across sources — revenue in Snowflake, customers in Salesforce, tickets in Jira, joined locally in DuckDB
• Investigate issues — check S3 logs, query databases, cross-reference config tables in one conversation
• Build dashboards and reports — describe what you want and Codex builds it, with shareable URLs
• Validate data quality — check for anomalies, reconcile across sources, catch pipeline breaks
• Build pipelines — pull, transform, validate, and export data across systems

Why plugin over raw MCP

You can connect to MarcoPolo via MCP alone. The plugin is better for three reasons:

Codex knows which workspace to use. With MCP alone, Codex has access to two computers — your local machine and the remote MarcoPolo workspace — and frequently uses the wrong one. The plugin teaches Codex which tools operate where.

Queries follow a proven workflow. A correct query requires discovering connections, reading business context and syntax docs, refreshing metadata, writing a query file, executing it, iterating if wrong, and joining through DuckDB for follow-up. With MCP alone, Codex has to figure this out from tool descriptions. The plugin encodes it as bundled skills.

Tools are always available. As you add MCP servers, Codex searches across tools dynamically and doesn't always find the right one. The plugin's skills give Codex direct knowledge of MarcoPolo's tools, bypassing the search.

Example prompts

These work out of the box with a personal email account (demo data included).

Explore and profile:

Profile our Snowflake warehouse — show me all tables, column types, null rates, and how the tables relate to each other. Save what you learn to RULES.md.

Cross-source analysis:

Pull last quarter's revenue from Snowflake and churned accounts from Salesforce. Join them in DuckDB and flag active accounts that match the churn pattern.

Investigate an issue:

The orders API has been slow since yesterday. Check the S3 event logs for a latency spike, query the Postgres job config for recent changes, and trace the root cause.

Build a report:

Break down customers by country and order status, then build me a dashboard.

Storage exploration:

Browse the S3 data lake. List directories under the bronze layer and check for Parquet files.

See Use Cases for detailed walkthroughs.

Installation

The recommended setup is a personal install so the plugin is available across projects.

mkdir -p ~/.codex/plugins
git clone https://github.com/immersa-co/marcopolo-plugin ~/.codex/plugins/marcopolo

Add or update ~/.agents/plugins/marketplace.json:

{
  "name": "my-plugins",
  "interface": {
    "displayName": "My Plugins"
  },
  "plugins": [
    {
      "name": "marcopolo",
      "source": {
        "source": "local",
        "path": "./.codex/plugins/marcopolo"
      },
      "policy": {
        "installation": "INSTALLED_BY_DEFAULT",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Then:

1. Restart Codex.
2. Open the plugin directory in Codex.
3. Select your personal marketplace.
4. Verify marcopolo appears installed by default or install it manually if your local policy differs.

Verify it works

After installation, confirm the plugin exposes the following skills:

• using-marcopolo-workspace
• using-connection-cli
• setup-connection
• query-and-analyze
• build-dashboard
• setup-automation

Also confirm the marcopolo MCP server loads from .mcp.json when you start a Codex session.

Then verify the connection:

> What connections do I have?

Codex should run `connection list --json` through workspace_shell and
return what's configured. If you haven't connected anything yet, ask it
to install a demo:

> Install the Snowflake demo so I can try MarcoPolo.

See Demo Connections for the full catalog.

What's in the plugin

The plugin is declarative — markdown and JSON files, no custom code.

Extending the plugin

The plugin is open source: github.com/immersa-co/marcopolo-plugin. Add your own skills, modify existing ones, or add workflows specific to your team. Skills are markdown files — no code required.