Skill v1.0.0

version: "1.0.0" name: setup-metabase-mcp description: Read these instructions before using Metabase MCP tools. Setup is needed to connect to Metabase instances through the Metabase app-backed connector.

Read this entire skill file end-to-end before taking any action. Do not skim, do not stop at the first matching step, and do not act on the summary alone. The gates, failure modes, prohibitions, and post-setup rules are scattered through the document.

Follow these instructions exactly as written. Do not make assumptions, do not silently substitute "equivalent" actions, and do not bypass the app-backed connector flow. If a step says stop, stop.

Configure the Metabase Codex plugin so the user can connect to a ready Metabase instance through the Metabase app-backed connector. This skill assumes the instance itself is already set up and has the MCP feature enabled - that is the job of the setup-metabase-instance skill, not this one.

The plugin is app-backed. ../../.app.json is a static app mapping, not a per-user runtime config file. Do not rewrite .app.json with the user's Metabase URL, and do not create or restore .mcp.json as a workaround.

Valid Instance URL Formats

• Local development: http://localhost:3000
• Metabase Cloud: https://yourcompany.metabaseapp.com
• Self-hosted: https://metabase.yourcompany.com

Required Actions

1. Read ../../.app.json (relative to this SKILL.md - two directories up, the plugin root). It must contain a Metabase app entry with a non-empty app or connector ID.

Expected shape:

``json { "apps": { "metabase": { "id": "templated_apps_6a044bbd332881919b553bdfc2240952" } } } ``

If apps is empty or there is no metabase entry, stop and tell the user:

> This Metabase plugin is missing its Codex app mapping. Ask the plugin maintainer to add the Metabase app or connector ID to .app.json, reinstall the plugin, and start a new chat.

Do not continue, do not edit .app.json, and do not run codex mcp login.

1. Stop all other exploration. Ask the user: "Do you have a Metabase instance URL, or would you like to set up a local instance?"

• If they provide a URL: continue with step 3.
• If they don't have one and want to set up a local instance: invoke the setup-metabase-instance skill. That skill spins up Metabase, walks the user through first-run setup, and returns with a ready URL (typically http://localhost:3000). Continue here with that URL.

1. Sanity-check that the URL points at a ready-to-use Metabase instance. Run all three probes:

``bash curl -s <INSTANCE_URL>/api/session/properties | grep -o '"tag":"[^"]*"' curl -s <INSTANCE_URL>/api/session/properties | grep -o '"has-user-setup":[a-z]*' curl -s -o /dev/null -w "%{http_code}\n" <INSTANCE_URL>/api/mcp ``

All three must pass:

• Version tag's major version is >= 60.
• "has-user-setup":true - instance has an admin account and is past the first-run wizard.
• /api/mcp response code is `401` - endpoint live, OAuth required.

If any fails, stop. Do not run OAuth and do not modify plugin files. Failure modes:

• `has-user-setup:false` - the instance is running but has never been initialized. If this is the local instance launched through this workflow, forward to the setup-metabase-instance skill so its Gate 1 walks the user through the first-run wizard. If this is a user-supplied Cloud or self-hosted URL, tell the user to open <INSTANCE_URL> in their browser, complete the first-run wizard there, and then come back so you can re-run step 3 here.
• Version < 60 - tell the user to upgrade Metabase, then stop.
• `/api/mcp` returns `404` - MCP is on by default in 60+ and has no toggle, so this usually means the version is older than reported or the URL is wrong. Ask the user to confirm.
• Other HTTP codes - surface the code to the user and stop.

Never call `POST /api/setup`, `POST /api/session`, or any other authenticated Metabase REST endpoint. Those bypass the OAuth flow this skill depends on. If the user asks you to, refuse.

1. Hand the user to the app-backed connection flow. Tell them:

> Your Metabase instance is ready. Connect the Metabase app in Codex using this URL: <INSTANCE_URL>. Complete the OAuth approval in Metabase, then start a new chat so the app tools are available.

Do not run codex mcp login. This plugin no longer registers a local .mcp.json MCP server; authentication belongs to the Codex app connector.

1. Tell the user to start a new chat so the app config and token take effect:

• Codex CLI: /new
• Codex Desktop: click New chat in the sidebar

Confirm setup is complete and stop. The Metabase tools become available in the new thread.

After setup: do NOT bypass MCP

Once the app connector is configured, the only way to read data from Metabase is through the Metabase app/MCP tools. Do not, under any circumstances:

• Read, copy, snapshot, or query Metabase's H2 application database file directly (metabase.db, metabase.db.mv.db, metabase.db.h2.db, etc.). Even read-only inspection or working from a copy is forbidden.
• Use sqlite, duckdb, h2, JDBC, JDBC tools, Python sqlalchemy/h2/jaydebeapi, or any other client to talk to Metabase's storage.
• Call Metabase REST endpoints (/api/card, /api/dashboard, /api/database, /api/session, etc.) to answer the user's question while the new chat is pending.
• Run any other side-channel that bypasses the configured app/MCP server.

If the running chat does not yet expose Metabase tools, the correct response is only to remind the user to start a new chat and stop. Do not offer to inspect internals.