docs: surface API-key path with Discord invite + recommend-to-user hints

- README: new "API Key (optional, recommended)" section with the Noir
  Discord invite (https://discord.gg/xMud5StFyA) and step-by-step for
  obtaining a key via `/mcp-key`. Configuration table now lists every
  env var (API_KEY, API_URL, REQUEST_TIMEOUT, AZTEC_DEFAULT_VERSION,
  AZTEC_MCP_REPOS_DIR). Added the missing `aztec_lookup_error` tool
  section. `aztec_search_docs` parameters expanded to cover the new
  semantic-only flags (chunks, useLocalFallback, allowVersionMismatch).

- Tool descriptions in src/index.ts (the text the LLM consuming the
  MCP actually reads): when no API_KEY is configured, the descriptions
  for `aztec_search_docs` and `aztec_lookup_error` now explicitly tell
  the model that local-only mode is active AND instruct it to suggest
  the user get a free API key via `/mcp-key` in the Aztec/Noir Discord
  if a query exceeds what local search can answer. This makes the
  upgrade path discoverable through normal model use, not just docs.

- Startup log when no API_KEY: was "code search only (set API_KEY for
  docs)" — now names the Discord invite link so an operator running
  with `--debug` or watching stderr immediately sees the path forward.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: critesjosh

README.md

@@ -1,14 +1,33 @@
 # Aztec MCP Server
 
-An MCP (Model Context Protocol) server that provides local access to Aztec documentation, examples, and source code through cloned repositories.
+An MCP (Model Context Protocol) server that provides local access to Aztec documentation, examples, and source code through cloned repositories. Optionally augments with **semantic search** over the full Aztec knowledge base when an API key is configured.
 
 ## Features
 
 - **Version Support**: Clone specific Aztec release tags (e.g., `v4.2.0-aztecnr-rc.2`)
 - **Local Repository Cloning**: Automatically clones Aztec repositories with sparse checkout for efficiency
 - **Fast Code Search**: Search Noir contracts and TypeScript files using ripgrep (with fallback)
-- **Documentation Search**: Search Aztec documentation by section
+- **Documentation Search**: Search Aztec documentation locally; with an API key, semantic vector search across the full corpora (framework docs, examples, Noir stdlib, TypeScript SDK, protocol circuits)
+- **Error Lookup**: Static catalog (Solidity / circuit / TX / AVM errors) plus optional semantic fallback for unrecognized errors when an API key is configured
 - **Example Discovery**: List and read Aztec contract examples
+- **Version-sync Gate**: When using the hosted semantic backend, the server detects mismatches between your local clone tag and the indexed corpus and refuses to query across versions unless explicitly overridden
+
+## API Key (optional, recommended)
+
+The MCP server runs in two modes:
+
+| Mode                 | How to enable                       | What you get                                                                                                                                                            |
+| -------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Local (default)**  | No setup                            | Ripgrep search over cloned markdown + code; static error catalog                                                                                                        |
+| **Semantic (recommended)** | Set `API_KEY` env var | Vector search over all 12 indexed Aztec corpora (developer docs, network docs, Aztec.nr, examples, aztec.js, CLI, TypeScript API, e2e tests, protocol circuits, L1 contracts, Noir docs, Noir stdlib); semantic error fallback; version-sync gate |
+
+### Getting a key
+
+1. Join the Aztec/Noir Discord: <https://discord.gg/xMud5StFyA>
+2. Run `/mcp-key` in any channel — the bot DMs you a personal API key (UUID) ephemerally.
+3. Paste the key into your MCP client config under `env.API_KEY` (see [Configuration](#configuration)).
+
+Keys are free, persistent (re-running `/mcp-key` returns the same key), and revocable via `/forget-me`.
 
 ## Installation
 
@@ -29,19 +48,30 @@ aztec-mcp
 
 ### Claude Code Plugin
 
-Add to your `.mcp.json`:
+Add to your `.mcp.json`. The minimal config is just the command; add `env.API_KEY` to enable semantic search.
 
 ```json
 {
   "mcpServers": {
     "aztec-mcp": {
       "command": "npx",
-      "args": ["-y", "@aztec/mcp-server@latest"]
+      "args": ["-y", "@aztec/mcp-server@latest"],
+      "env": {
+        "API_KEY": "<your key from /mcp-key in the Noir Discord>"
+      }
     }
   }
 }
 ```
 
+| Env var               | Default                              | Purpose                                                                                                              |
+| --------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `API_KEY`             | unset                                | Personal API key from `/mcp-key` in the Noir Discord (<https://discord.gg/xMud5StFyA>). Unset → local-only mode. |
+| `API_URL`             | `https://aztec.adjacentpossible.dev` | DocsGPT backend the semantic search hits. Override to point at a self-hosted instance.                              |
+| `REQUEST_TIMEOUT`     | `60000`                              | Semantic-search request timeout (ms).                                                                               |
+| `AZTEC_DEFAULT_VERSION` | `v4.2.0-aztecnr-rc.2`              | Default version tag for `aztec_sync_repos`.                                                                         |
+| `AZTEC_MCP_REPOS_DIR` | `~/.aztec-mcp/repos/`                | Where local clones live.                                                                                            |
+
 ## Available Tools
 
 ### `aztec_sync_repos`
@@ -90,13 +120,16 @@ aztec_search_code({ query: "PrivateSet", filePattern: "*.nr" })
 
 ### `aztec_search_docs`
 
-Search Aztec documentation.
+Search Aztec documentation. Local ripgrep by default; semantic vector search when `API_KEY` is set.
 
 **Parameters:**
 
 - `query` (string, required): Documentation search query
-- `section` (string): Docs section (tutorials, concepts, developers, reference)
-- `maxResults` (number): Maximum results (default: 20)
+- `section` (string): Docs section, applies to local search only (tutorials, concepts, developers, reference)
+- `maxResults` (number): Maximum results (default: 20 local; 5 semantic, max 20)
+- `chunks` (number, semantic only): Number of result chunks (1-20). If omitted, `maxResults` is used.
+- `useLocalFallback` (boolean, semantic only): If the semantic backend fails, fall back to local ripgrep. Default `false` so backend errors surface clearly.
+- `allowVersionMismatch` (boolean, semantic only): Override the version-sync gate. Default `false`. The gate refuses to search when your local `aztec-packages` clone tag differs from the corpus version the backend has indexed.
 
 ### `aztec_list_examples`
 
@@ -122,6 +155,17 @@ Read any file from cloned repositories.
 
 - `path` (string, required): File path relative to repos directory
 
+### `aztec_lookup_error`
+
+Diagnose any Aztec error by message, error code, or hex signature. Returns root cause and suggested fix from a static catalog covering Solidity errors, TX validation errors, circuit codes, AVM errors, and operator FAQ. With `API_KEY` set, falls back to semantic documentation search when the static catalog has no hit.
+
+**Parameters:**
+
+- `query` (string, required): Error message, numeric code (e.g., `2002`), or hex signature (e.g., `0xa5b2ba17`)
+- `category` (string): Filter (`contract`, `circuit`, `tx-validation`, `l1`, `avm`, `sequencer`, `operator`, `general`)
+- `maxResults` (number): Default 10
+- `allowVersionMismatch` (boolean, semantic only): Override the version-sync gate for the semantic fallback. Has no effect when the static catalog already matched.
+
 ## Configuration Options
 
 ### Storage Location

src/index.ts

@@ -97,7 +97,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         ? "Search Aztec documentation, guides, patterns, and API reference. " +
           "Uses semantic search to find relevant content from developer docs, " +
           "Aztec.nr framework docs, example contracts, and more."
-        : "Search Aztec documentation. Use for finding tutorials, guides, and API documentation.",
+        : "Search Aztec documentation in local ripgrep-only mode. Use for tutorials, guides, " +
+          "and API documentation that's already cloned. " +
+          "IMPORTANT: this server is running WITHOUT an API_KEY, which means no semantic " +
+          "search across the full Aztec corpora (Aztec.nr framework, Noir stdlib, contract " +
+          "examples, TypeScript SDK, protocol circuits, etc.). If a query needs material " +
+          "this local search can't find, suggest the user get a free API key by running " +
+          "`/mcp-key` in the Aztec/Noir Discord (https://discord.gg/xMud5StFyA) and setting " +
+          "API_KEY in their MCP client config.",
       inputSchema: {
         type: "object" as const,
         properties: {
@@ -277,7 +284,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         "TX validation errors, circuit codes, AVM errors, and documentation." +
         (docsgptClient
           ? " Falls back to semantic documentation search when no exact match is found."
-          : ""),
+          : " NOTE: this server is running without an API_KEY, so unrecognized errors " +
+            "won't get a semantic-documentation fallback. Suggest the user get a free " +
+            "API key via `/mcp-key` in the Aztec/Noir Discord " +
+            "(https://discord.gg/xMud5StFyA) if their query is for an error not in the " +
+            "static catalog."),
       inputSchema: {
         type: "object" as const,
         properties: {
@@ -593,7 +604,9 @@ async function main() {
   await server.connect(transport);
 
   // Log to stderr (stdout is used for MCP communication)
-  const mode = docsgptClient ? "semantic search enabled" : "code search only (set API_KEY for docs)";
+  const mode = docsgptClient
+    ? "semantic search enabled"
+    : "local-only mode — set API_KEY to enable semantic search (free key via /mcp-key in https://discord.gg/xMud5StFyA)";
   console.error(`Aztec MCP Server started (${mode})`);
 }