feat(altimate-code): experimental direct MCP data tools (Claude reasons, altimate-code supplies tools)

.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
     "url": "https://altimate.ai"
   },
   "metadata": {
-    "description": "Altimate's Claude Code plugin — delegates dbt and warehouse work to the altimate-code CLI agent.",
-    "version": "1.1.1"
+    "description": "Altimate's Claude Code plugin — direct MCP data tools and CLI delegation for long dbt and warehouse jobs.",
+    "version": "1.2.0-experimental"
   },
   "plugins": [
     {
       "name": "altimate-code",
-      "description": "Delegates dbt and warehouse work to altimate-code, a specialized CLI agent with 100+ purpose-built data tools (SQL analysis, column-level lineage, dbt build/test/run, warehouse profiling, FinOps, connectivity to Snowflake, BigQuery, Redshift, Databricks, Postgres, MySQL, DuckDB), and to the skills, knowledge and memory of a linked Altimate workspace.",
+      "description": "Use altimate-code data tools directly through MCP with Claude Code reasoning, or delegate long dbt and warehouse jobs to the altimate-code CLI agent.",
       "source": "./plugins/altimate-code",
       "strict": false
     }

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Thanks for taking the time to contribute. This plugin lives in one repo (`AltimateAI/altimate-claude-plugin`) and ships a single Claude Code plugin (`altimate-code`) that delegates data-engineering tasks to the [altimate-code](https://github.com/AltimateAI/altimate-code) CLI.
+Thanks for taking the time to contribute. This plugin lives in one repo (`AltimateAI/altimate-claude-plugin`) and ships a single Claude Code plugin (`altimate-code`). It prefers direct MCP tools for data questions and delegates to the [altimate-code](https://github.com/AltimateAI/altimate-code) CLI for other capabilities and long jobs. When MCP tools are unavailable, data questions also delegate, using the analyst persona. Both paths tell the user which is being used; delegation uses the CLI's separate configured LLM provider.
 
 ## Quick start
 
@@ -28,9 +28,12 @@ altimate-claude-plugin/
 │   └── altimate-code/
 │       ├── .claude-plugin/
 │       │   └── plugin.json      # plugin manifest
+│       ├── .mcp.json             # local stdio MCP server registration
 │       ├── skills/
 │       │   └── altimate-code/
-│       │       └── SKILL.md     # delegation logic
+│       │       └── SKILL.md     # MCP/delegation routing and CLI invocation
+│       ├── agents/
+│       │   └── analyst.md       # read-only data analyst for the MCP tools
 │       ├── hooks/
 │       │   └── hooks.json       # SessionStart hook config
 │       ├── hooks-handlers/
@@ -49,6 +52,8 @@ altimate-claude-plugin/
 ## What to change where
 
 - **Routing behavior** (when Claude picks up the skill): edit `plugins/altimate-code/skills/altimate-code/SKILL.md` frontmatter description and/or `plugins/altimate-code/hooks-handlers/session-start.sh` `additionalContext`.
+- **Direct data-question analysis**: edit `plugins/altimate-code/agents/analyst.md` (the server instructions carry the method).
+- **MCP server launch**: edit `plugins/altimate-code/.mcp.json` (`altimate-code mcp serve`, read-only by default).
 - **Explicit-invocation UX** (what `/altimate-code:altimate <task>` does): edit `plugins/altimate-code/commands/altimate.md`.
 - **CLI invocation details** (agent selection, flags, follow-up handling): edit the workflow section in `plugins/altimate-code/skills/altimate-code/SKILL.md`.
 
@@ -79,9 +84,11 @@ claude plugin install altimate-code@altimate-claude-plugin
 
 ## Components
 
-- **Skill** — `plugins/altimate-code/skills/altimate-code/SKILL.md` — the delegation logic (`altimate-code run "$USER_TASK"` and surface the result).
+- **Routing skill** — `plugins/altimate-code/skills/altimate-code/SKILL.md` — prefer available MCP tools for data questions; otherwise delegate to `altimate-code run` with `analyst`. Delegate other capabilities and long jobs using the appropriate persona.
+- **Analyst agent** — `plugins/altimate-code/agents/analyst.md` — read-only data analyst rules for the MCP tools.
+- **MCP registration** — `plugins/altimate-code/.mcp.json` — launches the local stdio server; builds without `mcp serve` fail to start it and use delegation instead.
 - **Hook** — `plugins/altimate-code/hooks/hooks.json` + `plugins/altimate-code/hooks-handlers/session-start.sh` — SessionStart hook that describes the plugin's capabilities in the system prompt so Claude can route to it when the task shape fits.
-- **Command** — `plugins/altimate-code/commands/altimate.md` — `/altimate-code:altimate` slash command for explicit delegation.
+- **Command** — `plugins/altimate-code/commands/altimate.md` — `/altimate-code:altimate` slash command follows the same MCP/delegation routing with agent-persona selection.
 
 ## Reporting bugs / requesting features
 

PRIVACY.md

@@ -1,32 +1,43 @@
 # Privacy Policy — Altimate Code plugin for Claude Code
 
-**Effective date:** July 9, 2026
-**Applies to:** the `altimate-code` Claude Code plugin distributed from this repository, and the data flows it initiates through the [altimate-code](https://github.com/AltimateAI/altimate-code) CLI.
+**Effective date:** October 17, 2026
+**Applies to:** the `altimate-code` Claude Code plugin distributed from this repository, and the data flows it initiates through the [altimate-code](https://github.com/AltimateAI/altimate-code) MCP server and CLI.
 
 This policy supplements the Altimate AI [Privacy Policy](https://www.altimate.ai/privacy) and [Terms](https://www.altimate.ai/terms), which govern Altimate services generally. Where this document is silent, the master policy applies. Questions: **info@altimate.ai**.
 
 ---
 
 ## The short version
 
-- The plugin itself collects **no data**. It is a routing layer (a skill, a slash command, and a static session hook) that tells Claude Code when to delegate a task to the altimate-code CLI installed on your machine.
+- When the plugin is enabled, Claude Code launches a local `altimate-code mcp serve` process for direct data tools. This requires a build containing `mcp serve`; if the server cannot start or its tools are unavailable, data questions fall back to CLI delegation.
+- MCP tool results, including sampled column values and query results, enter the Claude Code conversation and therefore reach your configured model provider. The local MCP server makes no separate LLM calls.
 - When a task **is** delegated, your task text is passed to the altimate-code CLI, which sends it to an LLM provider to plan and execute the work — the Altimate LLM Gateway by default, or a provider you configure (BYOK).
 - Warehouse queries, dbt commands, and file edits run **locally on your machine, under your credentials**. Your warehouse credentials are never sent to Altimate.
 - Installing the plugin is an explicit act — `/plugin marketplace add` does not install it, and `/plugin install` never auto-runs. Nothing is delegated until the plugin is installed and you send a task that matches the skill.
 
 ## What the plugin does and does not do
 
-The plugin contains no executable service of its own. Its only runtime behavior is a SessionStart hook that prints a fixed, static text block describing the skill's capabilities. It does not read your files, does not phone home, and does not collect analytics.
+The plugin registers a local stdio MCP server through `.mcp.json`, provides routing skills and slash commands, and runs a SessionStart hook that prints a fixed capability description. The server reads configured connections and runs data tools under your local credentials. The plugin adds no analytics of its own; CLI telemetry is described below.
 
-Data leaves Claude Code's process only when the delegation skill or the `/altimate-code:altimate` command fires and invokes the locally installed altimate-code CLI.
+## Data flows through MCP tools
+
+| Data | Where it goes | Retention |
+|---|---|---|
+| Database credentials and connection configuration | Read locally by the MCP server to connect to your databases | Local configuration; not included in tool results |
+| Schema metadata, sampled column values, and query results returned by tools | Local MCP server → Claude Code conversation → your configured model provider | Governed by Claude Code and your model provider's policies |
+| Scratch tables and spilled query results | Local session storage or spill files; any content Claude reads enters the conversation and reaches your model provider | Local artifacts; conversation copies follow Claude Code and provider policies |
+
+The MCP server makes no separate LLM calls. Delegation uses the separate provider path below.
+
+The delegation path below runs only when the delegation skill or the `/altimate-code:altimate` command fires and invokes the locally installed altimate-code CLI.
 
 ## Data flows when a task is delegated
 
 | Data | Where it goes | Retention |
 |---|---|---|
 | Your task prompt (verbatim) | Local altimate-code CLI → your configured LLM provider | Altimate LLM Gateway does not retain full prompts and responses after processing. BYOK providers: governed by that provider's policy — Altimate never sees this traffic. |
 | Warehouse credentials (`profiles.yml`, env vars) | Stay on your machine; used locally by the CLI | Never transmitted to Altimate |
-| Warehouse query results, dbt output, file edits | Produced locally; written to a local output file surfaced back to Claude Code | Local only |
+| Warehouse query results, dbt output, file edits | Produced locally; data supplied to the CLI agent reaches its configured LLM provider. Output read back into Claude Code reaches Claude Code's model provider. | Local output files; provider copies follow the applicable provider policies |
 | Schema metadata indexed by the CLI | Local index on your machine | Local only |
 
 **Bring Your Own Key (BYOK):** if you configure your own provider (Anthropic, OpenAI, Bedrock, Azure OpenAI, Ollama, and others), your prompts go directly from your machine to that provider. Altimate is not in the path.
@@ -57,8 +68,8 @@ All data transmitted to Altimate services is encrypted in transit using TLS. Alt
 
 ## Your choices
 
-- **Don't enable the plugin** — it ships disabled; nothing is delegated until you enable it.
-- **Use BYOK** — route prompts directly to your own provider so Altimate never sees them.
+- **Don't enable the plugin** — no plugin MCP server is launched and no tasks are delegated while it is disabled.
+- **Use BYOK for delegation** — route CLI agent prompts directly to your own provider. MCP tool results are handled by Claude Code's configured model provider independently.
 - **Disable telemetry** — see above.
 - **Contact us** — for access, correction, or deletion requests, email **info@altimate.ai**.
 

README.md

@@ -2,7 +2,24 @@
 
 The Altimate marketplace of Claude Code plugins.
 
-Currently ships one plugin: **[altimate-code](./plugins/altimate-code/)** — delegates dbt and warehouse work to the [altimate-code](https://github.com/AltimateAI/altimate-code) CLI agent.
+Currently ships one plugin: **[altimate-code](./plugins/altimate-code/)** — gives Claude Code direct MCP data tools from [altimate-code](https://github.com/AltimateAI/altimate-code), with CLI delegation for long dbt and warehouse jobs.
+
+**Experimental: direct MCP use requires an altimate-code build with `mcp serve`.**
+Released builds without `mcp serve` fail to start the MCP server; the plugin then
+falls back to `altimate-code run` with the analyst persona for data questions,
+using the CLI's configured LLM provider. The plugin tells you which path it uses.
+With MCP available, Claude Code
+supplies the reasoning and LLM cost for direct data questions; the MCP server
+runs no LLM. Tools: `warehouse_list`, `warehouse_add`, `sql_execute` (with `tables`
+for schemas and value profiles), `sql_materialize` (session-local scratch DuckDB for
+cross-database joins) and `answer_commit`.
+
+Source queries are read-only by default: database-enforced on Postgres, SQLite,
+and DuckDB; classification-only elsewhere, so use a read-only DB user. Connections
+come from project/global `.altimate-code/connections.json` and
+`ALTIMATE_CODE_CONN_*` environment variables, or an explicit `--connections <file>`
+server argument. See the [plugin README](./plugins/altimate-code/README.md) for setup,
+value profiles, result spill files, and the separate LLM billing for delegated jobs.
 
 ## Install
 

plugins/altimate-code/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "altimate-code",
   "displayName": "Altimate Code",
-  "version": "1.1.1",
-  "description": "Delegates dbt and warehouse work to altimate-code, a specialized CLI agent with 100+ purpose-built data tools (SQL analysis, column-level lineage, dbt build/test/run, warehouse profiling, FinOps, connectivity to Snowflake, BigQuery, Redshift, Databricks, Postgres, MySQL, DuckDB), and to the skills, knowledge and memory of a linked Altimate workspace.",
+  "version": "1.2.0-experimental",
+  "description": "Use altimate-code data tools directly through MCP with Claude Code reasoning, or delegate long dbt and warehouse jobs to the altimate-code CLI agent.",
   "author": {
     "name": "AltimateAI",
     "url": "https://altimate.ai"

plugins/altimate-code/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "altimate-code": {
+      "command": "altimate-code",
+      "args": ["mcp", "serve"]
+    }
+  }
+}

plugins/altimate-code/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this plugin will be documented in this file.
 
+## [1.2.0-experimental] — Unreleased — direct MCP use requires an altimate-code build with `mcp serve`
+
+### Added
+- Stdio MCP registration for `altimate-code mcp serve`, without `--allow-write`.
+- Direct data tools: `warehouse_list`, `warehouse_add`, `sql_execute` (`tables` returns schemas and value profiles in the same call), `sql_materialize` and `answer_commit`; `schema_inspect` and `sql_check` with `mcp serve --all-tools`.
+- `analyst` agent with the rules for value-profile inspection, SQL analysis, cross-connection scratch joins, and correctness checks. `answer_commit` is optional; the analyst may end with a plain `FINAL ANSWER:` line.
+
+### Changed
+- Routing skill and `/altimate-code:altimate` prefer MCP for data questions with Claude Code reasoning. If the MCP tools are unavailable, they fall back to CLI analyst delegation and tell the user which path is used. Released builds without `mcp serve` fail to start the MCP server and use this fallback.
+- Long jobs and capabilities outside the five MCP tools retain CLI delegation and agent-persona guidance.
+- Delegated runs use `builder` (no `fast-edit` persona) and the canonical-binary resolver from 1.1.x.
+- Documentation covers experimental prerequisites, connection discovery, read-only enforcement limits, local result files, and separate reasoning/billing paths.
+
 ## [1.1.1] — 2026-10-20
 
 ### Fixed