Getting Started

1. Connect your AI Client

The simplest way to connect is through MCP (Model Context Protocol), the standard for connecting AI assistants to external tools. For Claude and Codex, the plugins (Claude Plugin, Codex Plugin) provide a better experience with built-in skills for data workflows. Both options connect to the same MarcoPolo workspace.

Specialized Integrations

If you aren't using a standard MCP client, follow these specific guides:

• Claude Desktop Extension: Connect MarcoPolo to a free version of Claude Desktop via the desktop extension
• Claude Plugin: Plugin for Claude Code and Claude Desktop with bundled skills, MCP configuration, and data analyst subagent
• Codex Plugin: Plugin for OpenAI Codex with bundled skills and MCP configuration
• Developer SDKs: Use MCP or the Sandbox SDK to integrate MarcoPolo into custom LangChain agents or autonomous Python scripts.
• Replit:

2. Connect and Establish Identity

Once the server URL is added, you must explicitly Connect to the MarcoPolo MCP server within your AI app. This action triggers the authentication process. You can establish your identity using Google, Microsoft, GitHub, or by providing your Email address.

• Automatic Workspace Provisioning: The moment you first authenticate, MarcoPolo automatically provisions your workspace at /workspace. All subsequent queries, files, and cached data persist within this secure boundary.
• Domain-Based Enablement: Your email domain maps you to your company's environment, which lets you share connections, business context, and analysis artifacts with other users or groups within your organization.

3. Install a Demo Connection

You don't need real credentials to evaluate MarcoPolo. Install a hosted demo connection and the workspace is immediately useful.

Install the Snowflake demo so I can try MarcoPolo.

AI calls install_demo_connection(demo_connection="snowflake-demo")
   → success: true
   → connection installed at connections/snowflake-demo/

AI: Done. The Snowflake demo is installed. It has an ANALYTICS database
    with CUSTOMERS, ORDERS, and PRODUCT_METRICS tables. Want me to
    show you what's in it?

The seven demos cover the common shapes: a warehouse (snowflake-demo), a CRM (salesforce-demo), a lakehouse (aws-s3-demo), a public-dataset warehouse (bigquery-winequality-demo), a document database (mongodb-atlas-sample-dbs-demo), large-Parquet-on-S3 for performance work, and an SFTP server. See Demo Connections for what each one contains.

4. Run your First Query

Your AI inspects the connection's metadata, writes a query file into the workspace, executes it, and caches the full result in DuckDB before answering.

Who are the top customers by total purchases?

AI runs workspace_shell("connection list --json")
   → snowflake-demo (snowflake)  capabilities: [query, describe, test]

AI runs workspace_shell("cat connections/snowflake-demo/README.md SYNTAX.md")
AI runs workspace_shell("connection describe snowflake-demo --database ANALYTICS --table CUSTOMERS --json")
   → 10 columns: CUSTOMER_ID, CUSTOMER_NAME, EMAIL, COUNTRY,
     ACCOUNT_STATUS, TOTAL_PURCHASES, ...

AI writes connections/snowflake-demo/queries/top_customers.sql
AI runs workspace_shell("connection query snowflake-demo --file connections/snowflake-demo/queries/top_customers.sql --json")
   → 5 rows → DuckDB relation: snowflake_demo_top_customers

AI: Top 5 customers by total purchases:
    1. Fiona Green     (Germany)  $3,450.80
    2. Charlie Brown   (UK)       $2,340.00
    3. Jessica Martinez (Spain)   $2,100.00
    4. Hannah Lee      (Japan)    $1,890.45
    5. Alice Johnson   (USA)      $1,250.50

    Results are cached in DuckDB - you can run follow-up queries
    against this data without re-hitting Snowflake.

You've run your first query. The query file is saved at connections/snowflake-demo/queries/top_customers.sql, the full result is materialized as a DuckDB relation, and both persist in your workspace for follow-up analysis or reuse.

5. Connect your Own Data

When you're ready to work with production data, ask your AI to generate a setup link. You configure credentials in a secure web form — they're encrypted and never exposed to the AI.

I want to connect my PostgreSQL database.

AI calls connection_setup(type="pg")
   → URL: https://mcp.marcopolo.dev/app/connections/new?step=configure&type=pg
   → workflow_type: "configure"

AI: Open this link to configure your PostgreSQL connection. You'll
    enter your host, port, database name, and credentials in a secure
    form. Once saved, I can query it immediately.

Once configured, the new connection appears alongside the demos in connection list --json. The workflow is the same: your AI writes queries into connections/<name>/queries/, executes them, caches results in DuckDB, and you iterate.

What tables are in my Postgres database?

AI runs workspace_shell("connection describe my-postgres --database public --json")
   → 14 tables: customers, orders, invoices, products, ...

AI runs workspace_shell("connection describe my-postgres --database public --table customers --json")
   → 8 columns: id, name, email, created_at, plan, mrr, ...

Next Steps

• Browse the demo catalog: Pick the demo that matches the workflow you want to try.
• Connect your own data sources: Add the databases, warehouses, cloud storage, and SaaS applications you work with regularly.
• Open the Web App: Browse the files, query history, and dashboards your AI has created in your persistent workspace.
• Write a RULES.md: Define your business logic and metric definitions so the AI generates accurate queries consistently.
• Security overview: Review how MarcoPolo uses isolated containers and encrypted credential storage to protect your data.