Enhance instance setup instructions to handle database connection flow

[sanex3339]

See https://www.loom.com/share/cc327aa4bb2f4f438b7769467d38c86f for some context

Notes:

• currently Codex needs an explicit confirmation from user that a DB connection is set; one of the reasons - a user may want to setup multiple DBs; also there's no way to properly observe for connections currently without using REST API that needs auth
• I added some additional constraints as Codex constantly ignores some important instructions (medium effort)

How to test the Metabase plugin locally

1. Clone this repo.

2. Set up a local marketplace that points at the cloned plugin.

mkdir -p ~/codex-local/.agents/plugins ~/codex-local/plugins
cp --recursive /path/to/metabase-codex-plugin ~/codex-local/plugins/metabase

Note the --recursive flag; you need to copy the directory and its sub-directories because Codex caches a copy of the plugin and won't resolve symlinks when loading local plugins.

Then create ~/codex-local/.agents/plugins/marketplace.json:

{
  "name": "local-dev",
  "interface": { "displayName": "Local Dev" },
  "plugins": [
    {
      "name": "metabase",
      "source": { "source": "local", "path": "./plugins/metabase" },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Data"
    }
  ]
}

3. Register the marketplace with Codex.

codex plugin marketplace add ~/codex-local

4. Open Codex and install Metabase from the Local Dev marketplace:

   • Codex CLI: run the /plugins slash command.
   • Codex Desktop: open the Plugins menu and enable it there.

5. Prepare some local DB with data and its connection string

6. Ask Codex something like I want to try metabase and play with my local data.

7. Wait for instance loading, when codex opens the instance setup page - setup instance.

8. When instance is configured, Codex should auto-detect it and ask if you want to setup a DB connection.

9. Reply yes.

10. Codex will open the DB Connections setup page, setup it.

11. Reply Done

12. Codex will proceed with MCP setup and after it ask you to start a new thread.

13. In a new thread ask Codex to show some data from Metabase and your newly added DB

[Copilot]

Pull request overview

This PR updates the Metabase setup “skills” documentation to prevent broken MCP OAuth flows by adding stricter gating around instance readiness (especially first-run wizard completion) and by prompting users to optionally connect their own database before handing off to MCP configuration.

Changes:

• Added prominent “read fully / follow exactly” guardrails to both setup skills.
• Enhanced setup-metabase-mcp instance validation to include a has-user-setup readiness probe and explicit failure-mode handling.
• Expanded setup-metabase-instance initialization flow with a background polling Gate 1 and a mandatory Gate 2 prompt to connect a user database before handing off to MCP setup.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
skills/setup-metabase-mcp/SKILL.md	Adds stricter pre-OAuth instance readiness validation (version, has-user-setup, /api/mcp response) and clarifies stop/forward behavior.
skills/setup-metabase-instance/SKILL.md	Adds a background-poll-based first-run completion gate and a mandatory prompt to optionally connect a user database before MCP handoff.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[heypoom]

Confirmed that the database connection flow works on GPT-5.5 Medium on latest Codex. It shows the add connection admin settings page, then asks me to authorize Codex.

Token usage: total=214,318 input=207,734 (+ 1,194,752 cached) output=6,584 (reasoning 1,455)