From e334973019651247f260b22e86ae5aee915db075 Mon Sep 17 00:00:00 2001 From: mavneox Date: Mon, 22 Jun 2026 05:21:30 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs(mcp):=20fix=20#1=20install=20failure?= =?UTF-8?q?=20=E2=80=94=20lead=20with=20uv=20install=20+=20troubleshooting?= =?UTF-8?q?=20+=201-click=20deeplinks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit People hit "MCP server failed to connect"; root cause is uvx not installed. - Quick Install now leads with the cross-platform `uv` install command - "first launch ~30s" note (avoids connect timeout on first run) - pip/pipx fallback elevated to a first-class no-uvx path - Troubleshooting section keyed to the exact "cannot/failed to connect" error (uvx --version check, manual handshake test, pip escape hatch) - One-click install for the top 3: Claude Code (CLI), Cursor + VS Code (verified deeplinks) - Capability summary block (products / transport / access / auth / tools) Co-Authored-By: Claude Opus 4.8 --- src/content/docs/guides/claude-code.mdx | 116 ++++++++++++++++++++++-- 1 file changed, 107 insertions(+), 9 deletions(-) diff --git a/src/content/docs/guides/claude-code.mdx b/src/content/docs/guides/claude-code.mdx index e0c7319..4da0f64 100644 --- a/src/content/docs/guides/claude-code.mdx +++ b/src/content/docs/guides/claude-code.mdx @@ -8,18 +8,46 @@ import { Steps, Tabs, TabItem, Aside } from '@astrojs/starlight/components'; [Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's CLI for Claude. It supports **MCP (Model Context Protocol)** servers, which let Claude interact with external APIs through natural language. The Auto Content Engine MCP server gives Claude direct access to your GEN agents, content engines, rows, cells, generations, organizations, and assets. ## Quick Install -The fastest way — one command (requires [`uv`](https://docs.astral.sh/uv/)): +**Two commands. Copy, paste, done.** + +**1. Install `uv`** (the runner that fetches and launches the server). Skip this if you already have `uv`. + + + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + + +```powershell +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + + +```bash +brew install uv +``` + + + +**Open a new terminal** after installing `uv` so it's on your `PATH`. + +**2. Add the server to Claude Code:** ```bash claude mcp add gen --env GEN_API_KEY=your-pat -- uvx gen-mcp-server ``` -`uvx` fetches the latest `gen-mcp-server` from PyPI and runs it; there's nothing to install or keep up to date manually. +`uvx` fetches the latest `gen-mcp-server` from PyPI and runs it — there's nothing to install or keep up to date manually. The **first launch takes ~30 seconds** while it downloads; after that it's instant. + + Or follow the manual setup below. @@ -39,9 +67,26 @@ Or follow the manual setup below. If you lose your key, revoke it and create a new one. Keys cannot be retrieved after creation. -2. **Add the MCP server to Claude Code** +2. **Install `uv`** (one time) + + `uv` is the small, fast runner that fetches and launches the server. If you already have it (`uvx --version` works), skip this. + + + + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + + + ```powershell + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + ``` + + + + Then **open a new terminal** so `uv` is on your `PATH`. - The server is published on PyPI and runs with [`uv`](https://docs.astral.sh/uv/) — no manual install needed: +3. **Add the MCP server to Claude Code** ```bash claude mcp add gen --env GEN_API_KEY=gen_pat_a1b2c3d4e5f6... -- uvx gen-mcp-server @@ -63,16 +108,69 @@ Or follow the manual setup below. } ``` -