zuplo 6.70.53 → 6.70.55

package/docs/mcp-gateway/connect-clients/claude-code.mdx

@@ -0,0 +1,184 @@
+---
+title: "Connect Claude Code"
+sidebar_label: "Claude Code"
+description:
+  Connect Claude Code's CLI to a Zuplo MCP Gateway using `claude mcp add`,
+  authenticate over OAuth, and manage the connection from the `/mcp` slash
+  command.
+---
+
+[Claude Code](https://code.claude.com/) is Anthropic's command-line coding
+agent. It speaks the MCP Streamable HTTP transport natively and handles the
+OAuth flow against the gateway in your browser.
+
+## Prerequisites
+
+- A Zuplo project with the MCP Gateway plugin configured and at least one MCP
+  route. See the [quickstart](../quickstart.mdx) if you haven't set one up yet.
+- Claude Code installed and signed in. Install instructions are at
+  [code.claude.com](https://code.claude.com/).
+
+## Get the route URL
+
+Each MCP route in `config/routes.oas.json` is reachable at
+`https://{deploymentUrl}/{routePath}` once deployed — for example
+`https://{deploymentUrl}/mcp/linear-v1`.
+
+## Add the gateway
+
+From a terminal, run `claude mcp add` with the `http` transport, a friendly name
+for the server, and your route URL:
+
+```bash
+claude mcp add --transport http zuplo https://{deploymentUrl}/{routePath}
+```
+
+The name (`zuplo` above) is the identifier you'll see in `/mcp` and in any
+prompts that invoke the server. Pick whatever makes sense for your team.
+
+By default the server is registered at **local scope** for the current project.
+Use `--scope user` to make it available across every project on your machine, or
+`--scope project` to commit a `.mcp.json` file alongside your code so your whole
+team picks it up:
+
+```bash
+# Share with the team via .mcp.json in the repo root
+claude mcp add --transport http --scope project zuplo https://{deploymentUrl}/{routePath}
+```
+
+Once added, the configuration is written to one of:
+
+- `~/.claude.json` (local or user scope)
+- `.mcp.json` at the project root (project scope)
+
+You can also edit either file directly. The HTTP server entry has this shape:
+
+```json title=".mcp.json"
+{
+  "mcpServers": {
+    "zuplo": {
+      "type": "http",
+      "url": "https://{deploymentUrl}/{routePath}"
+    }
+  }
+}
+```
+
+## Authenticate
+
+The first time Claude Code talks to the gateway, the gateway returns
+`401 Unauthorized` and Claude Code marks the server as needing authentication.
+
+<Stepper>
+
+1. Inside a Claude Code session, run the `/mcp` slash command:
+
+   ```text
+   /mcp
+   ```
+
+2. Select the gateway entry and follow the browser prompt. Claude Code opens the
+   gateway's OAuth flow, you sign in with your identity provider, and the
+   gateway returns the access token to Claude Code.
+
+3. The gateway then displays the consent page with the upstream MCP server the
+   route depends on. Click **Connect** and complete the upstream OAuth flow,
+   then click **Authorize** to finish.
+
+4. Back in the terminal, run `/mcp` again to confirm the server is connected and
+   to see the tool count.
+
+</Stepper>
+
+Access tokens are stored securely (in the system keychain on macOS, in a
+credentials file on other platforms) and refresh automatically. To revoke
+access, open `/mcp` and choose **Clear authentication** for the server.
+
+## Use a fixed OAuth callback port
+
+By default, Claude Code picks a random local port for the OAuth callback. The
+gateway accepts any loopback redirect URI by default, so this works out of the
+box. If you have a strict identity provider that requires a fixed redirect URI
+registered in advance, pass `--callback-port`:
+
+```bash
+claude mcp add --transport http --callback-port 8080 \
+  zuplo https://{deploymentUrl}/{routePath}
+```
+
+## Use pre-configured OAuth credentials
+
+The gateway supports [Dynamic Client Registration (DCR)](../auth/overview.mdx),
+so Claude Code registers itself automatically. If you operate a strict
+environment that requires pre-registered OAuth clients instead, register an
+OAuth app with the gateway's identity provider, then pass the credentials when
+you add the server:
+
+```bash
+claude mcp add --transport http \
+  --client-id your-client-id --client-secret --callback-port 8080 \
+  zuplo https://{deploymentUrl}/{routePath}
+```
+
+The `--client-secret` flag prompts for the secret with masked input. Claude Code
+stores the secret in the system keychain, not in the config file.
+
+For non-interactive scripts, set the secret via the `MCP_CLIENT_SECRET`
+environment variable instead of the prompt:
+
+```bash
+MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
+  --client-id your-client-id --client-secret --callback-port 8080 \
+  zuplo https://{deploymentUrl}/{routePath}
+```
+
+## What Claude Code supports
+
+Claude Code uses OAuth 2.1 with PKCE and registers itself via Dynamic Client
+Registration. It supports the following MCP capabilities from the gateway:
+
+- **Tools** — invoke gateway-exposed tools during a session.
+- **Prompts** — surface prompts as `/mcp__<server>__<prompt>` slash commands.
+- **Resources** — reference resources with `@server:protocol://path` in prompts.
+- **Roots** — declare the project root to the server.
+- **Elicitation** — Claude Code shows form dialogs and opens URLs when a server
+  requests structured input or interactive authorization mid-task.
+
+## Manage the connection
+
+A few commands you'll use often:
+
+```bash
+# List every configured server
+claude mcp list
+
+# Show details for one server
+claude mcp get zuplo
+
+# Remove the server
+claude mcp remove zuplo
+```
+
+Inside a session, `/mcp` shows the live status of each server (connected,
+pending, failed), the number of tools each one exposes, and provides
+re-authentication and authentication-clearing commands per server.
+
+## Troubleshooting
+
+- **`/mcp` shows the server as failed.** Run `claude mcp get zuplo` to confirm
+  the URL is correct, then re-run `/mcp` to retry. Check the gateway's
+  deployment is healthy and the URL is reachable from your machine.
+- **"Incompatible auth server: does not support dynamic client registration."**
+  This appears if the gateway's identity provider blocks DCR. Either enable DCR
+  on the provider or use pre-configured OAuth credentials as shown above.
+- **The browser does not open during OAuth.** Copy the URL Claude Code prints in
+  the terminal and open it manually. If the callback fails, paste the full
+  callback URL from your browser's address bar into the prompt Claude Code
+  shows.
+
+## Related
+
+- [Connect MCP clients overview](./overview.mdx)
+- Anthropic's docs:
+  [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
+- [Authentication overview](../auth/overview.mdx)

package/docs/mcp-gateway/connect-clients/claude-desktop.mdx

@@ -0,0 +1,160 @@
+---
+title: "Connect Claude Desktop and Claude.ai"
+sidebar_label: "Claude Desktop"
+description:
+  Connect Claude Desktop or Claude.ai to a Zuplo MCP Gateway as a custom remote
+  connector, complete the OAuth flow, and start using your tools.
+---
+
+Claude Desktop and Claude.ai connect to remote MCP servers through **Custom
+Connectors**. Adding a Zuplo MCP route takes two steps: paste the route URL into
+Claude's connector settings, then complete the browser-based OAuth flow.
+
+## Prerequisites
+
+- A Zuplo project with the MCP Gateway plugin configured and at least one MCP
+  route. See the [quickstart](../quickstart.mdx) if you haven't set one up yet.
+- Claude Desktop installed, or access to Claude.ai in your browser.
+- A Claude plan that supports custom connectors. Per
+  [Anthropic's documentation](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp),
+  custom connectors are available on Free, Pro, Max, Team, and Enterprise plans.
+  Free plans are limited to one custom connector. Team and Enterprise plans
+  require an organization owner to add the connector first before individual
+  members can authenticate.
+
+## Get the route URL
+
+Each MCP route in `config/routes.oas.json` is reachable at
+`https://{deploymentUrl}/{routePath}` once deployed (or
+`http://127.0.0.1:9000/{routePath}` when running locally with `zuplo dev`). The
+`{routePath}` is the path you set on the route — for example `/mcp/linear-v1`.
+
+## Add the connector in Claude
+
+Both Claude Desktop and Claude.ai support custom connectors. The flow is nearly
+identical in each.
+
+<Stepper>
+
+1. **Open connector settings.**
+   - **Claude Desktop:** open **Settings** → **Connectors**.
+   - **Claude.ai:** open **Settings** → **Connectors** in the web app.
+
+2. **Add a custom connector.**
+
+   Scroll to the bottom of the Connectors list and click **Add custom
+   connector**.
+
+3. **Enter the gateway URL.**
+
+   Paste the route URL (for example `https://{deploymentUrl}/mcp/linear-v1`).
+   Optionally name the connector (the name is what Claude shows you in the
+   connector list and in tool results) and click **Add**.
+
+4. **Sign in to the gateway.**
+
+   Claude opens the gateway's OAuth flow in a browser. Sign in with the identity
+   provider you configured for the gateway — see the
+   [provider catalog](../auth/overview.mdx#identity-providers) for the full list
+   of supported IdPs.
+
+5. **Complete the upstream connection.**
+
+   The gateway shows a consent page with the upstream MCP server the route
+   proxies to. Click **Connect** next to the upstream and complete its OAuth
+   flow. Once it's connected, click **Authorize** to finish.
+
+6. **Verify the connector is active.**
+
+   Back in Claude, the new connector appears in your Connectors list. Open a
+   chat and click the attachment icon to confirm tools, prompts, and resources
+   from the gateway are available.
+
+</Stepper>
+
+:::tip
+
+You can adjust which tools Claude is allowed to use per connector. Open the
+connector in Settings → Connectors and toggle individual tools on or off.
+
+:::
+
+## What Claude Desktop supports
+
+Claude Desktop registers itself with the gateway through
+[Dynamic Client Registration (DCR)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
+
+Claude Desktop supports the following MCP capabilities from the gateway:
+
+- **Tools** — invoke gateway-exposed tools by name.
+- **Prompts** — surface prompts as commands in the chat interface.
+- **Resources** — attach resources to messages from the attachment menu.
+- **Roots** — declare filesystem boundaries to the server.
+- **MCP Apps** — render interactive HTML widgets inline in the conversation.
+
+Claude.ai (the web version) supports the same set, plus
+[Client ID Metadata Documents (CIMD)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
+in addition to DCR.
+
+## Use a manual config file (advanced)
+
+If you need to script the install or share the configuration with a team, Claude
+Desktop also reads `claude_desktop_config.json`. This approach uses
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a stdio bridge to
+the remote gateway. Use it if your version of Claude Desktop doesn't yet support
+custom remote connectors natively, or if you want the connector to start
+automatically on every launch without going through the UI.
+
+1. In Claude Desktop, open **Settings** → **Developer** → **Edit Config**. This
+   opens `claude_desktop_config.json` in your editor.
+2. Add or merge in the following entry, replacing `Zuplo MCP` with the name you
+   want to show, and the URL with your route URL:
+
+   ```json title="claude_desktop_config.json"
+   {
+     "mcpServers": {
+       "Zuplo MCP": {
+         "command": "npx",
+         "args": ["mcp-remote", "https://{deploymentUrl}/{routePath}"]
+       }
+     }
+   }
+   ```
+
+3. Save the file and restart Claude Desktop.
+4. The first time Claude Desktop starts the bridge, it opens a browser window to
+   complete the OAuth flow against the gateway. Sign in and approve the consent
+   page as you would for a native connector.
+5. Verify the server appears in Claude Desktop. Tools are available behind the
+   attachment icon.
+
+:::note
+
+The native custom-connector flow above is the recommended path because it
+supports all of Claude Desktop's MCP features out of the box and does not
+require Node.js. Use the `mcp-remote` bridge only when you specifically need the
+file-based configuration.
+
+:::
+
+## Troubleshooting
+
+- **Browser does not open during OAuth.** Verify the gateway's deployment URL is
+  reachable from your machine and your firewall or proxy allows outbound HTTPS
+  to the gateway origin.
+- **Consent page shows "Connect" for every upstream every time.** This means the
+  gateway never received the user's signed-in identity. Confirm that your IdP is
+  configured correctly and that browser cookies are enabled for the gateway
+  origin.
+- **Tools do not appear after a successful authorization.** Open the connector
+  in Settings → Connectors and check that each tool is enabled. Disabled tools
+  are hidden from the attachment menu.
+
+## Related
+
+- [Connect MCP clients overview](./overview.mdx)
+- Anthropic's official guide:
+  [Connect to remote MCP servers](https://modelcontextprotocol.io/docs/develop/connect-remote-servers)
+- Anthropic's setup article:
+  [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp)
+- [Authentication overview](../auth/overview.mdx)

package/docs/mcp-gateway/connect-clients/cursor.mdx

@@ -0,0 +1,100 @@
+---
+title: "Connect Cursor"
+sidebar_label: "Cursor"
+description:
+  Connect Cursor to a Zuplo MCP Gateway using a one-click deeplink or by editing
+  `mcp.json` directly, complete the OAuth flow, and use gateway tools in Cursor
+  Composer.
+---
+
+[Cursor](https://cursor.com/) is an AI-first code editor. It speaks the MCP
+Streamable HTTP transport natively and supports OAuth-protected remote MCP
+servers, which is exactly what the Zuplo MCP Gateway exposes.
+
+Add the gateway connector in Cursor by editing Cursor's `mcp.json` configuration
+or by using a deeplink that opens Cursor and adds the entry.
+
+## Prerequisites
+
+- A Zuplo project with the MCP Gateway plugin configured and at least one MCP
+  route. See the [quickstart](../quickstart.mdx) if you haven't set one up yet.
+- Cursor installed and signed in.
+
+## Get the route URL
+
+Each MCP route in `config/routes.oas.json` is reachable at
+`https://{deploymentUrl}/{routePath}` once deployed — for example
+`https://{deploymentUrl}/mcp/linear-v1`.
+
+## Edit mcp.json
+
+Cursor reads MCP server configuration from two locations:
+
+- `~/.cursor/mcp.json` — applies to every project you open with Cursor.
+- `.cursor/mcp.json` in a project's root — applies only to that project, and can
+  be committed to version control to share with your team.
+
+Add an entry under `mcpServers`, using a friendly name as the key and the route
+URL as the value:
+
+```json title="~/.cursor/mcp.json"
+{
+  "mcpServers": {
+    "Zuplo MCP": {
+      "url": "https://{deploymentUrl}/{routePath}"
+    }
+  }
+}
+```
+
+Restart Cursor after editing the file. The first time Cursor connects, it opens
+a browser to complete the OAuth flow.
+
+### Environment variable interpolation
+
+Cursor's `mcp.json` supports interpolation so you don't need to hardcode
+sensitive values:
+
+- `${env:NAME}` — resolves to the environment variable `NAME`.
+- `${workspaceFolder}` — resolves to the project root.
+- `${userHome}` — resolves to your home directory.
+
+These work inside `command`, `args`, `env`, `url`, and `headers`. For example,
+to use a per-environment deployment URL:
+
+```json
+{
+  "mcpServers": {
+    "Zuplo MCP": {
+      "url": "${env:ZUPLO_MCP_URL}"
+    }
+  }
+}
+```
+
+## What Cursor supports
+
+Cursor registers itself with the gateway through Dynamic Client Registration and
+supports:
+
+- **Tools** — invoke gateway-exposed tools from Composer.
+- **Prompts** — surface gateway prompts in the prompt picker.
+- **Roots** — declare the project root to the server.
+- **Elicitation** — handle form-mode and URL-mode elicitation requests from the
+  gateway, including upstream re-authorization prompts.
+- **MCP Apps** — render interactive HTML widgets from compatible servers.
+
+## Troubleshooting
+
+- **Cursor shows "Failed to connect" for the server.** Open `~/.cursor/mcp.json`
+  and confirm the URL is correct and reachable. If the gateway is healthy,
+  restart Cursor to retry the OAuth flow.
+- **Tools do not refresh after upstream changes.** Restart Cursor or toggle the
+  server off and back on in the MCP settings. Cursor caches the tool list per
+  server.
+
+## Related
+
+- [Connect MCP clients overview](./overview.mdx)
+- Cursor's docs: [Model Context Protocol](https://cursor.com/docs/context/mcp)
+- [Authentication overview](../auth/overview.mdx)

package/docs/mcp-gateway/connect-clients/other-clients.mdx

@@ -0,0 +1,207 @@
+---
+title: "Other MCP clients"
+sidebar_label: "Other clients"
+description:
+  Add a Zuplo MCP Gateway to Windsurf, Goose, Gemini CLI, GitHub Copilot CLI,
+  Postman, MCPJam, Continue, LibreChat, and JetBrains AI Assistant.
+---
+
+The Zuplo MCP Gateway works with any MCP client that speaks the Streamable HTTP
+transport. The pages in this section give the basics for several popular clients
+beyond the ones with dedicated guides ([Claude Desktop](./claude-desktop.mdx),
+[Claude Code](./claude-code.mdx), [ChatGPT](./chatgpt.mdx),
+[Cursor](./cursor.mdx), [VS Code](./vs-code.mdx)).
+
+For each client, the pattern is the same: paste your MCP route URL
+(`https://{deploymentUrl}/{routePath}`, for example
+`https://{deploymentUrl}/mcp/linear-v1`) into the client's configuration, then
+complete the gateway's OAuth flow in your browser when prompted.
+
+## Windsurf
+
+[Windsurf](https://windsurf.com/) is an agentic IDE from Codeium with a built-in
+AI flow called **Cascade**. Cascade supports stdio, Streamable HTTP, and the
+older SSE transport, with OAuth available on each.
+
+To add the gateway, edit `~/.codeium/windsurf/mcp_config.json` and add an entry
+under `mcpServers`:
+
+```json title="~/.codeium/windsurf/mcp_config.json"
+{
+  "mcpServers": {
+    "zuplo": {
+      "serverUrl": "https://{deploymentUrl}/{routePath}"
+    }
+  }
+}
+```
+
+Windsurf supports environment-variable interpolation with `${env:VAR_NAME}` in
+the config so you don't have to hardcode the URL or any header values.
+
+Restart Cascade and complete the gateway's OAuth flow in your browser when
+prompted.
+
+Capabilities supported: tools.
+
+Docs: [Windsurf Cascade MCP](https://docs.windsurf.com/windsurf/cascade/mcp).
+
+## Goose
+
+[Goose](https://block.github.io/goose/) is Block's open-source AI agent. Goose
+supports the Streamable HTTP transport for remote MCP servers — it calls them
+**remote extensions**.
+
+To add the gateway from the Goose CLI:
+
+```bash
+goose configure
+```
+
+Choose **Add Extension** → **Remote Extension (Streamable HTTP)** and follow the
+prompts. Enter your route URL when asked. From the Goose Desktop app, open
+**Settings** → **Extensions** → **Add custom extension** and paste the same URL.
+
+Goose then opens the gateway's OAuth flow in your browser. Sign in and complete
+the upstream consent page.
+
+Capabilities supported: tools, prompts, resources, roots, sampling, elicitation,
+MCP Apps.
+
+Docs:
+[Goose extensions](https://block.github.io/goose/docs/getting-started/using-extensions).
+
+## Gemini CLI
+
+The [Gemini CLI](https://github.com/google-gemini/gemini-cli) is Google's
+open-source terminal agent for Gemini. Configure MCP servers in
+`~/.gemini/settings.json` under the `mcpServers` key:
+
+```json title="~/.gemini/settings.json"
+{
+  "mcpServers": {
+    "zuplo": {
+      "httpUrl": "https://{deploymentUrl}/{routePath}"
+    }
+  }
+}
+```
+
+Restart the CLI. The Gemini CLI registers itself with the gateway through
+Dynamic Client Registration and opens the OAuth flow in your browser on first
+connect.
+
+Capabilities supported: tools, prompts.
+
+Docs:
+[Gemini CLI MCP server configuration](https://geminicli.com/docs/tools/mcp-server/).
+
+## GitHub Copilot CLI
+
+The [GitHub Copilot CLI](https://github.com/features/copilot/cli/) is GitHub's
+terminal agent. Use the `/mcp add` slash command from inside a Copilot CLI
+session to add the gateway. Copilot CLI prompts for the server name, transport
+(`http`), and URL, then writes the entry to `~/.copilot/mcp-config.json` and
+starts the OAuth flow.
+
+Capabilities supported: tools, sampling, elicitation, OAuth Client Credentials.
+
+Docs:
+[Add an MCP server](https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#add-an-mcp-server).
+
+## Postman
+
+[Postman](https://www.postman.com/) supports MCP server testing and debugging
+through its AI Agent Builder. Create a new MCP request, choose **Streamable
+HTTP**, and paste your MCP route URL. Postman handles the OAuth flow inline.
+
+Postman is a useful client for verifying that an MCP route responds correctly,
+inspecting raw JSON-RPC traffic, and debugging tool schemas.
+
+Capabilities supported: tools, prompts, resources, sampling, elicitation, MCP
+Apps.
+
+Docs: [Postman download](https://www.postman.com/downloads/) (MCP support is
+built into the standard Postman desktop client).
+
+## MCPJam
+
+[MCPJam Inspector](https://github.com/MCPJam/inspector) is an open-source local
+development client for MCP servers, ChatGPT apps, and MCP App extensions. It's a
+strong tool for verifying gateway behavior end-to-end during development.
+
+Launch the inspector, set the transport to **Streamable HTTP**, and paste your
+MCP route URL. MCPJam runs the OAuth flow and shows tools, prompts, resources,
+and any MCP Apps the gateway exposes.
+
+Capabilities supported: tools, prompts, resources, elicitation, MCP Apps, DCR,
+CIMD, Tasks.
+
+Docs: [MCPJam getting started](https://docs.mcpjam.com/getting-started).
+
+## Continue
+
+[Continue](https://www.continue.dev/) is an open-source AI code assistant that
+runs in VS Code and JetBrains IDEs. Continue supports MCP servers in **agent
+mode** only.
+
+Add the gateway either by editing your main Continue config or by creating a
+standalone YAML file under `.continue/mcpServers/`. For a remote HTTP server:
+
+```yaml title=".continue/mcpServers/zuplo.yaml"
+name: zuplo
+version: 0.0.1
+schema: v1
+mcpServers:
+  - name: zuplo
+    type: streamable-http
+    url: https://{deploymentUrl}/{routePath}
+```
+
+Capabilities supported: tools, prompts, resources, MCP Apps.
+
+Docs:
+[Continue MCP deep dive](https://docs.continue.dev/customize/deep-dives/mcp).
+
+## LibreChat
+
+[LibreChat](https://github.com/danny-avila/LibreChat) is an open-source
+self-hosted AI chat UI. LibreChat supports MCP servers as additional tool
+sources.
+
+Add the gateway in the `mcpServers` section of your `librechat.yaml`
+configuration, restart the LibreChat server, and complete the OAuth flow the
+first time you select the connector in a conversation.
+
+Capabilities supported: tools.
+
+Docs: [LibreChat MCP](https://www.librechat.ai/docs/features/mcp).
+
+## JetBrains AI Assistant
+
+The
+[JetBrains AI Assistant](https://plugins.jetbrains.com/plugin/22282-jetbrains-ai-assistant)
+plugin is available in every JetBrains IDE. It supports MCP servers as sources
+of tools for the AI Assistant.
+
+Open the AI Assistant settings, add an MCP server, and paste your MCP route URL.
+Complete the OAuth flow in your browser when prompted.
+
+Capabilities supported: tools.
+
+Docs:
+[Model Context Protocol in JetBrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/mcp.html).
+
+## Other clients
+
+For an up-to-date list of MCP clients, see the official
+[MCP clients page](https://modelcontextprotocol.io/clients). Any client that
+supports the Streamable HTTP transport and standard MCP authorization (RFC 9728
+Protected Resource Metadata plus OAuth 2.1) will work with the Zuplo MCP Gateway
+out of the box.
+
+## Related
+
+- [Connect MCP clients overview](./overview.mdx)
+- [Authentication overview](../auth/overview.mdx)
+- [Configuring the MCP Gateway with code](../code-config/overview.mdx)