upstash · fahreddinozcan · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026
diff --git a/.changeset/tidy-clis-connect.md b/.changeset/tidy-clis-connect.md
@@ -0,0 +1,5 @@
+---
+"ctx7": minor
+---
+
+Add outbound-independent on-premise MCP setup through `ctx7 setup --base-url`, including secure interactive personal API-key entry and anonymous-auth discovery support.
diff --git a/docs/clients/cli.mdx b/docs/clients/cli.mdx
@@ -128,7 +128,8 @@ ctx7 setup --opencode
 # Target a specific install location (CLI + Skills mode)
 ctx7 setup --cli --claude       # Claude Code (~/.claude/skills)
 ctx7 setup --cli --cursor       # Cursor (~/.cursor/skills)
-ctx7 setup --cli --universal    # Universal (~/.agents/skills)
+ctx7 setup --cli --codex        # Codex (~/.agents/skills)
+ctx7 setup --cli --opencode     # OpenCode (~/.agents/skills)
 ctx7 setup --cli --antigravity  # Antigravity (~/.agent/skills)
 
 # Configure for current project only (default is global)
@@ -150,6 +151,31 @@ ctx7 setup --oauth
 
 Without `--api-key` or `--oauth`, setup runs the OAuth device flow: it shows a verification link and short code that you open on any device to sign in, so it works the same locally or on a remote, headless, or SSH host. MCP mode additionally generates a new API key after login. `--oauth` is MCP-only — use it when an IDE handles the auth flow on your behalf.
 
+### On-premise setup
+
+Pass the root URL of your on-premise deployment with `--base-url`. Do not include `/mcp` or `/api`:
+
+```bash
+# MCP authentication disabled on the deployment
+ctx7 setup --mcp --base-url https://context7.internal.example --codex
+
+# MCP authentication enabled: the CLI requests the personal key with hidden input
+ctx7 setup --mcp \
+  --base-url https://context7.internal.example \
+  --codex
+
+# Non-interactive automation
+CONTEXT7_API_KEY=ctx7op-... ctx7 setup --mcp --yes \
+  --base-url https://context7.internal.example \
+  --codex
+```
+
+The CLI checks `/api/auth/mcp` before writing configuration. It either configures anonymous access or writes `Authorization: Bearer <personal-key>`. When authentication is enabled and no key was provided, interactive setup requests the key with masked input. Use `--api-key` or `CONTEXT7_API_KEY` for non-interactive automation. On-premise setup uses Streamable HTTP and bundled rule/skill content, so the target does not need to serve Context7 Cloud skill endpoints.
+
+When `--base-url` targets a custom deployment, setup skips the npm update check and telemetry and does not fetch rules or skills from GitHub or Context7 Cloud. After the CLI package is installed, the only network request made by setup is to the configured deployment. In a restricted environment, mirror `ctx7` and its dependencies in an internal npm registry and run the installed `ctx7` binary instead of `npx ctx7@latest`.
+
+`--base-url` currently supports MCP setup only. It cannot be combined with `--oauth`, `--stdio`, or `--cli` for a custom deployment.
+
 **What gets written — MCP mode:**
 
 | File                                                | Purpose                                                          |
@@ -221,7 +247,8 @@ export CONTEXT7_API_KEY=your_key
 | Feature                                                  | Required                                                                     |
 | -------------------------------------------------------- | ---------------------------------------------------------------------------- |
 | `ctx7 library` / `ctx7 docs`                             | No — login gives higher rate limits                                          |
-| `ctx7 setup`                                             | Yes — unless `--api-key` is passed (`--oauth` also skips login for MCP mode) |
+| Hosted `ctx7 setup`                                      | Yes — unless `--api-key` is passed (`--oauth` also skips login for MCP mode) |
+| On-premise `ctx7 setup --mcp --base-url ...`             | Only when MCP authentication is enabled on the deployment                    |
 
 ---
 

diff --git a/docs/enterprise/api/authentication.mdx b/docs/enterprise/api/authentication.mdx
@@ -61,4 +61,6 @@ Certain operations can be allowed without authentication. Configure them from **
 | Anonymous parse / refresh | Off |
 | Anonymous delete | Off |
 
-The search (`GET /v2/libs/search`) and context (`GET /v2/context`) endpoints are always publicly accessible unless a global `API_KEY` environment variable is set, in which case every endpoint requires a bearer token.
+MCP authentication is configured separately in **Settings > Authentication**. When enabled, external requests to `/mcp`, `/api/v2/libs/search`, and `/api/v2/context` require a personal API key. When disabled, those endpoints allow anonymous access. The local MCP bridge can still call the v2 endpoints over loopback.
+
+The legacy global `API_KEY` environment variable protects the broader HTTP API independently of personal MCP keys. New deployments should use dashboard users and personal keys for MCP clients.
diff --git a/docs/enterprise/on-premise.mdx b/docs/enterprise/on-premise.mdx
@@ -65,7 +65,7 @@ You can also add libraries via the REST API:
 ```bash
 curl -X POST http://localhost:3000/api/parse \
   -H "Content-Type: application/json" \
-  -d '{"url": "https://github.com/your-org/your-repo"}'
+  -d '{"repoUrl": "https://github.com/your-org/your-repo"}'
 ```
 
 </Step>
@@ -74,37 +74,85 @@ curl -X POST http://localhost:3000/api/parse \
 
 ## Connecting Your AI Client
 
-Point your MCP client at your deployment URL. Replace `https://context7.internal.yourcompany.com` with your actual host.
+The Context7 CLI is the recommended way to connect an AI coding agent. Install it once on the machine that runs your client:
 
-### Claude Code
+<Tabs>
+  <Tab title="Public npm registry">
+    ```bash
+    npm install --global ctx7@latest
+    ```
+  </Tab>
+  <Tab title="Internal npm registry">
+    ```bash
+    npm install --global ctx7 \
+      --registry https://npm.internal.yourcompany.com
+    ```
+  </Tab>
+</Tabs>
+
+For restricted or air-gapped environments, mirror the `ctx7` package and its dependencies in your approved internal npm registry. Once installed, on-premise setup does not contact npm, GitHub, or Context7 Cloud. It uses bundled rule and skill content and contacts only your deployment to discover its MCP authentication setting.
+
+Pass the root URL of your deployment (without `/mcp` or `/api`) and select the client:
+
+<Tabs>
+  <Tab title="Claude Code">
+    ```bash
+    ctx7 setup --mcp \
+      --base-url https://context7.internal.yourcompany.com \
+      --claude
+    ```
+  </Tab>
+  <Tab title="Cursor">
+    ```bash
+    ctx7 setup --mcp \
+      --base-url https://context7.internal.yourcompany.com \
+      --cursor
+    ```
+  </Tab>
+  <Tab title="Codex">
+    ```bash
+    ctx7 setup --mcp \
+      --base-url https://context7.internal.yourcompany.com \
+      --codex
+    ```
+  </Tab>
+  <Tab title="OpenCode">
+    ```bash
+    ctx7 setup --mcp \
+      --base-url https://context7.internal.yourcompany.com \
+      --opencode
+    ```
+  </Tab>
+</Tabs>
+
+Setup reads the deployment's MCP authentication setting. When MCP authentication is disabled, no credential is written. When it is enabled, sign in to the on-premise dashboard and click **Generate setup key** in the Connect card. Run the command for your client and paste the one-time-visible key when the CLI requests it with hidden input.
+
+For non-interactive automation, provide the personal key through the environment:
 
 ```bash
-claude mcp add --scope user --transport http context7 https://context7.internal.yourcompany.com/mcp
+CONTEXT7_API_KEY=ctx7op-... ctx7 setup --mcp --yes \
+  --base-url https://context7.internal.yourcompany.com \
+  --claude
 ```
 
-### Cursor
+You can use `--api-key ctx7op-...` instead, but command-line arguments may be retained in shell history. Setup writes the MCP client configuration, a Context7 rule, and a bundled `context7-mcp` skill. The bundled files mean the deployment does not need to expose Context7 Cloud's skill APIs.
 
-Add to `~/.cursor/mcp.json`:
+<Note>
+  Custom `--base-url` setup uses the deployment's Streamable HTTP endpoint. Hosted OAuth, local stdio transport, and CLI-query mode are not available for on-premise targets.
+</Note>
 
-```json
-{
-  "mcpServers": {
-    "context7": {
-      "url": "https://context7.internal.yourcompany.com/mcp"
-    }
-  }
-}
-```
+### Manual configuration
 
-### Opencode
+If your client is not supported by `ctx7 setup`, point it at `<deployment-root>/mcp`. When MCP authentication is enabled, send the personal key as a standard bearer token:
 
 ```json
 {
-  "mcp": {
+  "mcpServers": {
     "context7": {
-      "type": "remote",
       "url": "https://context7.internal.yourcompany.com/mcp",
-      "enabled": true
+      "headers": {
+        "Authorization": "Bearer ctx7op-..."
+      }
     }
   }
 }
@@ -186,16 +234,17 @@ You only need tokens for the platforms you use. If you only parse GitLab repos,
 
 Admin credentials are set during first login (default: `admin` / `admin`). Change these immediately after setup via **Settings > Change Credentials**.
 
-The Settings page lets you control which operations are available without authentication.
+The Settings page lets you control which operations are available without authentication, including MCP and API search access.
 
 | Permission | Default | Description |
 |---|---|---|
 | Allow anonymous parse | Off | Allow unauthenticated users to trigger parsing |
 | Allow anonymous refresh | Off | Allow unauthenticated users to refresh libraries |
 | Allow anonymous delete | Off | Allow unauthenticated users to delete libraries |
 | Allow anonymous support bundle | Off | Allow unauthenticated support bundle downloads |
+| Require MCP authentication | Off | Require a personal API key for `/mcp` and external `/api/v2` search requests |
 
-When a permission is off, the operation requires admin login. The MCP endpoint and search API are always publicly accessible.
+When MCP authentication is enabled, each user creates personal keys from **Personal Settings > API Keys**. Clients send the key as `Authorization: Bearer <key>`.
 
 ## Policies
 

diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -86,13 +86,28 @@ ctx7 setup --api-key YOUR_API_KEY
 # Use OAuth endpoint (IDE handles auth flow)
 ctx7 setup --oauth
 
+# Configure an on-premise deployment (pass the deployment root)
+ctx7 setup --mcp --base-url https://context7.internal.example --codex
+
+# When on-premise MCP auth is enabled, the CLI prompts for the key with hidden input
+ctx7 setup --mcp \
+  --base-url https://context7.internal.example \
+  --codex
+
+# For non-interactive automation, provide the key through the environment
+CONTEXT7_API_KEY=ctx7op-... ctx7 setup --mcp --yes \
+  --base-url https://context7.internal.example \
+  --codex
+
 # Configure for current project only (default is global)
 ctx7 setup --project
 
 # Skip prompts
 ctx7 setup --yes
 ```
 
+For a custom `--base-url`, setup discovers whether MCP authentication is enabled and writes either an anonymous HTTP entry or an `Authorization: Bearer` header. Interactive setup requests the personal key with masked input, keeping it out of shell history; `--api-key` and `CONTEXT7_API_KEY` remain available for automation. Setup uses bundled rule and skill content and skips the npm update check and telemetry, so after `ctx7` is installed it contacts only the configured deployment. Enterprise environments can mirror `ctx7` and its dependencies in an internal npm registry. Custom deployments support MCP HTTP setup; hosted OAuth, stdio, and CLI-query mode are not supported for on-premise targets.
+
 ### Uninstall setup
 
 Remove the Context7 setup written by `ctx7 setup`. By default this removes both MCP setup and CLI setup for the selected agent.
@@ -134,12 +149,14 @@ ctx7 logout
 
 The CLI automatically detects which AI coding assistants you have installed and configures Context7 for them:
 
-| Client                                                              | Skills Directory  |
-| ------------------------------------------------------------------- | ----------------- |
-| Universal (Amp, Codex, Gemini CLI, GitHub Copilot, OpenCode + more) | `.agents/skills/` |
-| Claude Code                                                         | `.claude/skills/` |
-| Cursor                                                              | `.cursor/skills/` |
-| Antigravity                                                         | `.agent/skills/`  |
+| Client      | Skills Directory  |
+| ----------- | ----------------- |
+| Claude Code | `.claude/skills/` |
+| Cursor      | `.cursor/skills/` |
+| OpenCode    | `.agents/skills/` |
+| Codex       | `.agents/skills/` |
+| Antigravity | `.agent/skills/`  |
+| Gemini CLI  | `.gemini/skills/` |
 
 ## Disabling Telemetry