MCP Tools

MarcoPolo exposes four MCP tools. Almost everything else — listing connections, testing credentials, inspecting metadata, querying, browsing storage, scheduling jobs — happens inside the workspace through the connection and cron CLIs, which your AI invokes via workspace_shell.

You don't call these by name. Your AI picks the right one based on what you ask. But understanding them helps when you want more control or need to debug unexpected behavior.

workspace_shell

Runs a command in the remote workspace.

workspace_shell(command, timeout=30)

This is how your AI reads files, writes queries, runs scripts, drives the connection and cron CLIs, and inspects git state. The workspace is a Linux environment at /workspace — anything you can do from a shell, your AI can do here.

You: "What data do I have access to?"

Your AI runs workspace_shell("connection list --json") and reads the result.

You: "Pull last quarter's revenue."

Your AI writes a query file with workspace_shell (heredoc into connections/<name>/queries/<file>.sql), then runs connection query <name> --file ... --json through workspace_shell to execute it.

This single tool replaces a half-dozen narrower MCP tools that earlier versions of MarcoPolo exposed. The benefit: one capability, full Linux semantics, and the workspace becomes the durable surface — not a constantly-shifting MCP API.

connection_setup

Generates a browser URL for setting up a credentialed connection.

connection_setup(type, intent_text=None)

When you want to set up a real connection, your AI calls this and surfaces the returned URL. You complete the setup in your browser — credentials never pass through the AI.

You: "I want to connect our Postgres."

AI calls connection_setup(type="pg")
   → URL: https://mcp.marcopolo.dev/app/connections/new?...
   → workflow_type: "configure"
   → instructions: "Open the URL, enter host/port/credentials, save."

type should be a canonical type code (pg, mysql, snowflake, bigquery, s3, salesforce, google_drive, local_file, etc.). If your AI passes a non-canonical hint plus intent_text, the tool resolves the intent and returns a URL — or, if it can't, returns valid_types and suggested_types so the AI can retry.

install_demo_connection

Installs a hosted demo connection directly — no browser flow, no credentials.

install_demo_connection(demo_connection, display_name=None, intent_text=None)

Use this to evaluate MarcoPolo without bringing your own data, or to reproduce a workflow against a known dataset. See Demo Connections for the full catalog and what each demo contains.

You: "Set me up with the Snowflake demo."

AI calls install_demo_connection(demo_connection="snowflake-demo")
   → success: true
   → connection installed; ready for `connection list --json`

If demo_connection is ambiguous, the response carries available_demo_connections and the AI re-prompts with a specific id.

preview_dashboard

Opens an interactive preview UI for a workspace .dashboard manifest.

preview_dashboard(path)

Dashboards in MarcoPolo are two files under artifacts/dashboards/: a .dashboard JSON manifest declaring named DuckDB datasets, and a view.tsx React component that renders them. preview_dashboard resolves the manifest's datasets against DuckDB and renders the view.

You: "Build a dashboard from the revenue query and let me see it."

AI writes artifacts/dashboards/revenue.dashboard
AI writes artifacts/dashboards/view.tsx
AI calls preview_dashboard(path="artifacts/dashboards/revenue.dashboard")
   → preview URL opens

See Build a Dashboard for the authoring contract.

How the four tools fit together

A typical question chains them:

1. workspace_shell("connection list --json") — what's available?
2. workspace_shell("cat connections/<name>/README.md ...") — read the seeded docs.
3. workspace_shell("connection describe <name> --json") — refresh metadata if stale.
4. workspace_shell("""cat > connections/<name>/queries/<file>.sql <<'SQL' ...SQL""") — author the query.
5. workspace_shell("connection query <name> --file ... --json") — execute, materialize into DuckDB.
6. preview_dashboard(...) if there's a visual artifact at the end.

connection_setup and install_demo_connection only show up at the start of a workflow, when a connection isn't there yet.

For verb-level reference (every flag of connection list, connection query, connection browse, cron create, etc.), see Connection & cron CLIs.