consolidate to single Cadence MCP — flow mcp (Flow CLI)

Per team confirmation that Peter Argue (Flow DX) ported Hao's MCP into
the Flow CLI in onflow/flow-cli#2306 (merged 2026-04-03), the canonical
Cadence MCP is now `flow mcp` — bundled with every Flow CLI install,
zero extra dependencies. flow-ai-tools' install script registers it
this way already.

The /onflow/cadence-lang.org redesign PR was carrying a parallel
`mcp-server/` (Hao's npm @outblock/cadence-mcp source). Two MCPs both
registering as 'cadence-mcp' in Claude Code is a footgun. Consolidating
to one canonical path.

CHANGES:

Docs — replace every '@outblock/cadence-mcp' install snippet with
'flow mcp' equivalent across:
- content/docs/ai-tools/mcp-server.mdx — full rewrite around Flow CLI
- content/docs/ai-tools/integrations/{claude,cursor,antigravity,opencode}.mdx
- content/docs/ai-tools/integrations/index.mdx (table + intro)
- content/docs/ai-tools/skills.mdx (Next steps; description re-counted)
- content/docs/ai-tools/index.mdx
- src/routes/index.tsx — homepage hero MCP card
- README.md — install commands
- AGENTS.md, CLAUDE.md — repo overview

Source — remove duplicate implementation:
- mcp-server/ (entire dir): 21 files, ~8200 lines deleted
- .github/workflows/publish-mcp.yml — npm publish CI no longer needed

Skill-count phrasing — replaced hardcoded '11 skills' / '11 Cadence + Flow
skills' with 'full Cadence + Flow skill suite' / 'Flow's full skill
suite' across all 8 affected files. The skill table in skills.mdx still
documents every skill by name with its description — count-free wording.

Follow-up issues to file post-merge:
- Upstream Hao's 3 unique tools (cadence_security_scan,
  cadence_validate_args, doc-search trio) into onflow/flow-cli/internal/mcp
- Deprecate @outblock/cadence-mcp on npm with redirect notice pointing
  at 'flow mcp'
- Confirm Flow DX team owns flow mcp going forward (Peter Argue)

Verified: types:check clean, build clean (96 sitemap URLs), zero
'@Outblock' / '@outblock/cadence-mcp' / 'mcp-server/' source references
remain in shipped content.

Author: Aliserag

.github/workflows/publish-mcp.yml

@@ -4,7 +4,7 @@ Guidance for AI coding agents working in this repository. Loaded into agent cont
 
 ## Overview
 
-`cadence-lang.org` is the documentation and marketing site for the Cadence smart contract programming language (Flow network). Built with TanStack Start (file-based routing + Nitro SSR) + Fumadocs (MDX docs engine) + Tailwind CSS v4 + Bun. Deployed on Vercel. Includes a standalone MCP server (`mcp-server/`, published to npm as `@outblock/cadence-mcp`), AI chat (`/api/chat`), Orama-powered search, and `/llms.txt` + `/llms-full.txt` LLM-optimized endpoints.
+`cadence-lang.org` is the documentation and marketing site for the Cadence smart contract programming language (Flow network). Built with TanStack Start (file-based routing + Nitro SSR) + Fumadocs (MDX docs engine) + Tailwind CSS v4 + Bun. Deployed on Vercel. Includes AI chat (`/api/chat`), Orama-powered search (federated with onflow/docs via the `external/onflow-docs` submodule), and `/llms.txt` + `/llms-full.txt` LLM-optimized endpoints. The Cadence MCP server is built into the Flow CLI as `flow mcp` ([source](https://github.com/onflow/flow-cli/tree/master/internal/mcp)), not bundled in this repo.
 
 ## Build and Test Commands
 
@@ -17,16 +17,9 @@ Bun ≥ 1.0 required. Node ≥ 22 (Vercel uses 24.x).
 - `bun run types:check` — `fumadocs-mdx && tsc --noEmit`. May report errors against the `external/onflow-docs` submodule's own files; those are out-of-scope for this repo.
 - `git submodule update --init --recursive` — populate `external/onflow-docs` (required before search index can include onflow-docs content)
 
-MCP server (separate workspace at `mcp-server/`):
+The Cadence MCP server is bundled with the Flow CLI as `flow mcp` (Flow CLI ≥ v2.16.0). Source at [onflow/flow-cli/internal/mcp](https://github.com/onflow/flow-cli/tree/master/internal/mcp); maintained by Flow DX. Not bundled in this repo.
 
-- `cd mcp-server && bun install`
-- `bun test:unit` — unit tests only (no Flow CLI required)
-- `bun test:integration` — integration tests (requires Flow CLI installed)
-- `bun run build` — bundle for npm publish
-- `bun run start` — stdio MCP transport
-- `bun run start:http` — HTTP transport (Hono) on configurable port
-
-CI: `.github/workflows/publish-mcp.yml` publishes `@outblock/cadence-mcp` to npm on tagged releases. No site-build CI in this repo — Vercel builds previews on every PR push.
+No site-build CI in this repo — Vercel builds previews on every PR push.
 
 ## Architecture
 
@@ -53,7 +46,6 @@ CI: `.github/workflows/publish-mcp.yml` publishes `@outblock/cadence-mcp` to npm
   - `ai-tools/` — MCP server, skills, LLM endpoints, integration guides (claude/cursor/codex/gemini/antigravity/opencode)
   - top-level pages: anti-patterns, design-patterns, security-best-practices, solidity-to-cadence, testing-framework, contract-upgrades, json-cadence-spec, project-development-tips, measuring-time, why, index
 - `content/docs/**/meta.json` — fumadocs section / page ordering; replaces Docusaurus `_category_.json`
-- `mcp-server/` — standalone Bun workspace, published to npm
 - `external/onflow-docs` — git submodule of `onflow/docs`, indexed for cross-site search; **not** rendered in the docs nav
 - `public/` — static assets served at root: `robots.txt`, `assets/`, `fonts/`, etc.
 - `vercel.json` — URL redirects (legacy paths, type-page moves). Update here when restructuring URLs.
@@ -80,23 +72,22 @@ CI: `.github/workflows/publish-mcp.yml` publishes `@outblock/cadence-mcp` to npm
 - **`/api/chat`** — Anthropic streaming via `@ai-sdk/anthropic`. `ANTHROPIC_API_KEY` is server-only and never reaches the browser bundle.
 - **Search** — Orama index built from `content/docs/` + `external/onflow-docs/` content. Search panel at `src/components/search.tsx`, Cmd+/ hotkey, localStorage persistence.
 - **`/llms.txt`** / **`/llms-full.txt`** — TanStack server routes that emit LLM-optimized markdown summaries / corpus.
-- **MCP server** at `mcp-server/` — exposes `cadence_check`, `cadence_search`, `cadence_execute_script`, `cadence_validate_args`, `cadence_security_scan`, `get_contract_source`. Both stdio and HTTP transports.
+- **MCP server** — `flow mcp` (Flow CLI built-in). Exposes `cadence_check`, `cadence_hover`, `cadence_definition`, `cadence_symbols`, `cadence_completion`, `get_contract_source`, `get_contract_code`, `cadence_execute_script`. stdio transport. Source: [onflow/flow-cli/internal/mcp](https://github.com/onflow/flow-cli/tree/master/internal/mcp).
 
 ## Conventions and Gotchas
 
-- **Bun is the toolchain.** Don't introduce npm/yarn lock files — `bun.lock` is the source of truth. Top-level `package.json` and `mcp-server/package.json` are independent workspaces.
+- **Bun is the toolchain.** Don't introduce npm/yarn lock files — `bun.lock` is the source of truth.
 - **`NODE_OPTIONS=--max-old-space-size=8192`** is required for the build (baked into `package.json` script). The SSR `source-*.mjs` chunk grew past the 4GB default heap when the `external/onflow-docs` submodule was added.
 - **Submodule pinning matters.** `external/onflow-docs` is pinned to a specific commit (not branch-tracking). Bumping the pin is a semi-supply-chain action; review the diff before updating.
 - **Tailwind v4 has no config file.** Theme tokens are CSS variables in `src/styles/app.css`. Use `cn()` from `src/lib/cn.ts` for class merging (clsx + tailwind-merge).
 - **Dark mode uses the `dark` class on `<html>`** (Fumadocs convention).
 - **URL redirects belong in `vercel.json`**, not page frontmatter. When moving / renaming pages, add the redirect there.
 - **Don't edit `routeTree.gen.ts`, `.source/`, or `.vercel/output/`.** All auto-generated.
-- **Cadence MCP HTTP endpoint is currently hosted on Outblock's Railway** (`https://cadence-mcp.up.railway.app/mcp`). The integration guides reference this URL — coordinate with @onflow before changing.
 - **Licensing is split:** source under Apache 2.0 (`LICENSE.txt`), content under CC-BY-4.0 (`CC-BY-4.0.txt`); see `LICENSE.md`.
 
 ## Files Not to Modify
 
-- `bun.lock`, `mcp-server/bun.lock`, `mcp-server/package-lock.json` — regenerated by `bun install`
+- `bun.lock` — regenerated by `bun install`
 - `.source/`, `.vercel/output/`, `node_modules/`, `build/` — build artifacts
 - `src/routeTree.gen.ts` — auto-generated by TanStack
 - `external/onflow-docs/` — submodule pointer; modify by bumping the pin in a deliberate commit

AGENTS.md

@@ -13,15 +13,10 @@ npm run dev          # Dev server on port 3000
 npm run build        # Production build + sitemap generation
 npm run start        # Run built server (node .output/server/index.mjs)
 npm run types:check  # TypeScript + MDX type checking (fumadocs-mdx && tsc --noEmit)
-
-# MCP server (separate workspace in mcp-server/)
-cd mcp-server
-bun run build        # Build
-bun test             # All tests
-bun test:unit        # Unit tests only
-bun test:integration # Integration tests (requires Flow CLI)
 ```
 
+The Cadence MCP server is bundled with the Flow CLI as `flow mcp` (Flow CLI ≥ v2.16.0); it lives at [onflow/flow-cli/internal/mcp](https://github.com/onflow/flow-cli/tree/master/internal/mcp), not in this repo.
+
 ## Architecture
 
 ### Framework Stack
@@ -37,7 +32,6 @@ bun test:integration # Integration tests (requires Flow CLI)
 - `src/components/` — React components; `ui/` has shadcn-style primitives
 - `src/lib/` — Utilities, Fumadocs source config, Cadence TextMate grammar
 - `content/docs/` — All MDX documentation files
-- `mcp-server/` — Standalone MCP server package (published to npm as `@outblock/cadence-mcp`)
 - `.source/` — Auto-generated by Fumadocs (do not edit)
 
 ### Routing Patterns

CLAUDE.md

@@ -8,22 +8,22 @@ Live at [cadence-lang.org](https://cadence-lang.org).
 
 ### Skills
 
-Install the Cadence skill for your AI coding agent:
+Install Flow's Claude Code skill suite from the [`onflow/flow-ai-tools`](https://github.com/onflow/flow-ai-tools) marketplace. In Claude Code:
 
-```sh
-npx skills add outblock/cadence-lang.org
+```bash
+/plugin marketplace add onflow/flow-ai-tools
+/plugin install flow-dev@flow-ai-tools
+/reload-plugins
 ```
 
 ### MCP Server
 
-Install the [Cadence MCP server](https://www.npmjs.com/package/@outblock/cadence-mcp) for AI-powered Cadence development — code checking, type info, and doc search:
+The Cadence MCP server is built into the [Flow CLI](https://developers.flow.com/tools/flow-cli) (≥ v2.16.0) as `flow mcp`. Source: [onflow/flow-cli/internal/mcp](https://github.com/onflow/flow-cli/tree/master/internal/mcp).
 
 ```sh
-npx install-mcp @outblock/cadence-mcp --client claude
+claude mcp add --scope user cadence-mcp -- flow mcp
 ```
 
-Supported clients: `claude`, `cursor`, `windsurf`, `copilot`, `vscode`
-
 ### LLM Context
 
 | Endpoint | Description |

README.md

@@ -5,7 +5,7 @@ title: AI Tools
 Cadence is designed for AI-native development. Three integrations make Cadence documentation and language intelligence available to any AI agent:
 
 - **[Skills](/docs/ai-tools/skills)** — inject Cadence knowledge into AI coding agents with one command
-- **[MCP Server](/docs/ai-tools/mcp-server)** — give AI agents live access to documentation search and the Cadence language server
+- **[MCP Server](/docs/ai-tools/mcp-server)** — `flow mcp` from the Flow CLI: gives AI agents type checking, symbol lookup, contract source fetching, and read-only on-chain script execution
 - **[LLM Endpoints](/docs/ai-tools/llm-endpoints)** — plain-text documentation endpoints optimized for LLM context windows
 
 ## Agent integrations

content/docs/ai-tools/index.mdx

@@ -18,21 +18,21 @@ Quick index: https://cadence-lang.org/llms.txt
 Resources use `@` prefix and must be moved with `<-`. Use `access(all)` for public access (not `pub`). Capability-based access control with entitlements.
 ```
 
-If you also use Claude Code, install the [flow-ai-tools](https://github.com/onflow/flow-ai-tools) marketplace there for richer skill coverage — it ships 11 Cadence + Flow skills (see [Skills](../skills)).
+If you also use Claude Code, install the [flow-ai-tools](https://github.com/onflow/flow-ai-tools) marketplace there for richer skill coverage — it ships the full Cadence + Flow skill suite (see [Skills](../skills)).
 
 ## Add MCP server
 
-Add the Cadence MCP server to your Antigravity configuration — runs locally via stdio:
+Add the Cadence MCP server to your Antigravity configuration — calls the Flow CLI's built-in `flow mcp` subcommand:
 
 ```json
 {
   "mcpServers": {
-    "cadence": {
-      "command": "npx",
-      "args": ["-y", "@outblock/cadence-mcp"]
+    "cadence-mcp": {
+      "command": "flow",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-This gives Antigravity access to all [MCP tools](../mcp-server) — documentation search, code checking, type inspection, security scanning, and more. Requires the [Flow CLI](https://developers.flow.com/tools/flow-cli) installed locally for the LSP-based tools.
+This gives Antigravity access to all [MCP tools](../mcp-server) — Cadence code checking, type inspection, symbol lookup, contract source fetching, and read-only on-chain script execution. Requires [Flow CLI](https://developers.flow.com/tools/flow-cli) ≥ v2.16.0.

content/docs/ai-tools/integrations/antigravity.mdx

@@ -8,7 +8,7 @@ Configure Claude to work with Cadence via skills, MCP, or context injection.
 
 ### Install Flow's skill library
 
-The official [onflow/flow-ai-tools](https://github.com/onflow/flow-ai-tools) marketplace ships 11 Cadence + Flow skills under one plugin:
+The official [onflow/flow-ai-tools](https://github.com/onflow/flow-ai-tools) marketplace ships the full Cadence + Flow skill suite under one plugin:
 
 ```bash
 /plugin marketplace add onflow/flow-ai-tools
@@ -20,10 +20,10 @@ See [Skills](../skills) for the full skill list.
 ### Add MCP server
 
 ```bash
-claude mcp add cadence-mcp -- npx -y @outblock/cadence-mcp
+claude mcp add --scope user cadence-mcp -- flow mcp
 ```
 
-This runs the [Cadence MCP server](../mcp-server) locally via stdio — gives Claude Code access to documentation search, Cadence code checking, type inspection, security scanning, and more. Requires the [Flow CLI](https://developers.flow.com/tools/flow-cli) installed locally for the LSP-based tools.
+This registers the [Cadence MCP server](../mcp-server) — built into the Flow CLI as the `flow mcp` subcommand. Gives Claude Code access to Cadence code checking, type inspection, symbol lookup, contract source fetching, and read-only on-chain script execution. Requires [Flow CLI](https://developers.flow.com/tools/flow-cli) ≥ v2.16.0.
 
 ## Claude Desktop
 
@@ -32,9 +32,9 @@ Add the Cadence MCP server to your `claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
-    "cadence": {
-      "command": "npx",
-      "args": ["-y", "@outblock/cadence-mcp"]
+    "cadence-mcp": {
+      "command": "flow",
+      "args": ["mcp"]
     }
   }
 }

content/docs/ai-tools/integrations/claude.mdx

@@ -22,7 +22,7 @@ Key conventions:
 - Use capability-based access control with entitlements
 ```
 
-If you also use Claude Code, install the [flow-ai-tools](https://github.com/onflow/flow-ai-tools) marketplace there for richer skill coverage — it ships 11 Cadence + Flow skills (see [Skills](../skills)).
+If you also use Claude Code, install the [flow-ai-tools](https://github.com/onflow/flow-ai-tools) marketplace there for richer skill coverage — it ships the full Cadence + Flow skill suite (see [Skills](../skills)).
 
 ## Context injection
 

content/docs/ai-tools/integrations/codex.mdx

@@ -24,16 +24,14 @@ Full Cadence reference: https://cadence-lang.org/llms-full.txt
 Quick index: https://cadence-lang.org/llms.txt
 ```
 
-If you also use Claude Code, install the [flow-ai-tools](https://github.com/onflow/flow-ai-tools) marketplace there for richer skill coverage — it ships 11 Cadence + Flow skills (see [Skills](../skills)).
+If you also use Claude Code, install the [flow-ai-tools](https://github.com/onflow/flow-ai-tools) marketplace there for richer skill coverage — it ships the full Cadence + Flow skill suite (see [Skills](../skills)).
 
 ## Add MCP server
 
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=cadence&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBvdXRibG9jay9jYWRlbmNlLW1jcCJdfQ==)
+In Cursor settings → MCP → Add new server:
 
-Or manually add in Cursor settings:
-
-- **Name**: `cadence`
+- **Name**: `cadence-mcp`
 - **Type**: `command`
-- **Command**: `npx -y @outblock/cadence-mcp`
+- **Command**: `flow mcp`
 
-This runs the [Cadence MCP server](../mcp-server) locally via stdio — gives Cursor access to documentation search, Cadence code checking, type inspection, security scanning, and more. Requires the [Flow CLI](https://developers.flow.com/tools/flow-cli) installed locally for the LSP-based tools.
+This registers the [Cadence MCP server](../mcp-server) — built into the Flow CLI as the `flow mcp` subcommand. Gives Cursor access to Cadence code checking, type inspection, symbol lookup, contract source fetching, and read-only on-chain script execution. Requires [Flow CLI](https://developers.flow.com/tools/flow-cli) ≥ v2.16.0.

content/docs/ai-tools/integrations/cursor.mdx

@@ -24,7 +24,7 @@ Key conventions:
 - Use capability-based access control with entitlements
 ```
 
-If you also use Claude Code, install the [flow-ai-tools](https://github.com/onflow/flow-ai-tools) marketplace there for richer skill coverage — it ships 11 Cadence + Flow skills (see [Skills](../skills)).
+If you also use Claude Code, install the [flow-ai-tools](https://github.com/onflow/flow-ai-tools) marketplace there for richer skill coverage — it ships the full Cadence + Flow skill suite (see [Skills](../skills)).
 
 ## Gemini API