From ebdfddce7ed32c1a8aff5080fc9f8593798f40ee Mon Sep 17 00:00:00 2001 From: Alex Idowu Date: Fri, 17 Jul 2026 22:25:58 +0100 Subject: [PATCH] docs: expand hosted MCP client setup --- .dockerignore | 7 ++ Dockerfile | 11 +- docs/Integrations/pipeops-mcp.md | 205 +++++++++++++++++++++++++++---- 3 files changed, 193 insertions(+), 30 deletions(-) create mode 100644 .dockerignore diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..8a15961 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,7 @@ +.git +.github +.docusaurus +build +node_modules +npm-debug.log* +yarn-error.log* diff --git a/Dockerfile b/Dockerfile index 7898245..20c0c4e 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,7 +1,4 @@ ARG NODE_IMAGE=node:20-alpine -ARG ENV=production -ARG PORT=8000 -ARG HOST=0.0.0.0 FROM $NODE_IMAGE AS build @@ -17,12 +14,16 @@ RUN yarn install && \ # Stage 2: Create the production image FROM $NODE_IMAGE AS prod +ARG ENV=production +ARG PORT=8000 +ARG HOST=0.0.0.0 + # Set the working directory in the container to /opt/app WORKDIR /opt/app # Set environment variable ENV NODE_ENV=$ENV -ENV ENV=production +ENV ENV=$ENV ENV PORT=$PORT ENV HOST=$HOST @@ -39,4 +40,4 @@ COPY --from=build /opt/app/build ./build COPY --from=build /opt/app/docusaurus.config.js . # Command to run docusaurus -CMD ["sh", "-c", "yarn run serve --host 0.0.0.0 --port $PORT"] +CMD ["sh", "-c", "yarn run serve --host \"$HOST\" --port \"$PORT\""] diff --git a/docs/Integrations/pipeops-mcp.md b/docs/Integrations/pipeops-mcp.md index ae6a1de..1a6cf70 100644 --- a/docs/Integrations/pipeops-mcp.md +++ b/docs/Integrations/pipeops-mcp.md @@ -2,7 +2,7 @@ slug: /integrations/pipeops-mcp sidebar_position: 0 title: Connect AI assistants with PipeOps MCP -description: "Connect Codex and other MCP clients to your PipeOps account through the hosted PipeOps MCP server." +description: "Connect Codex, ChatGPT, Claude, Cursor, VS Code, Gemini CLI, Windsurf, and Zed to PipeOps through the hosted MCP server." --- # Connect AI assistants with PipeOps MCP @@ -11,11 +11,13 @@ PipeOps MCP lets AI assistants inspect and manage resources in your PipeOps acco You do not need to install or run a local MCP server. -| Setting | Value | -| -------------- | ----------------------------- | -| MCP endpoint | `https://mcp.pipeops.app/mcp` | -| Transport | Streamable HTTP | -| Authentication | Bearer service token | +| Setting | Value | +| --- | --- | +| Name | `pipeops` | +| MCP endpoint | `https://mcp.pipeops.app/mcp` | +| Transport | Streamable HTTP | +| Recommended authentication | OAuth | +| Alternative authentication | Bearer service token | ## Find PipeOps MCP in the Console @@ -42,12 +44,69 @@ Create a dedicated service token for your AI client: Start with `api:read`. Create a separate, short-lived token for write access instead of granting `api:full` to a general-purpose assistant. ::: -## Connect Codex +## Choose an authentication method -Store the token in an environment variable: +### OAuth (recommended) + +Use OAuth when your client supports remote MCP authorization. Add the PipeOps MCP endpoint and select **Connect**, **Sign in**, or **Authorize**. The client discovers the PipeOps authorization endpoints automatically. + +The PipeOps authorization page asks for the dedicated service token you created. This one-time exchange happens on `https://mcp.pipeops.app`; the AI client does not receive or store the raw PipeOps token. The client receives short-lived OAuth credentials instead. + +OAuth access is read-only by default. If the client lets you select scopes, request `api:write` only when you want it to expose mutating tools. The consent page shows the requested access before approval. + +### Bearer service token + +Use a static Bearer token when your client supports custom HTTP headers or environment-variable secrets. The client sends the service token directly to PipeOps MCP on each request. Prefer an environment variable, password input, or client secret store over a token written directly in a configuration file. + +## Client compatibility + +| Client | OAuth | Bearer token | Recommended setup | +| --- | --- | --- | --- | +| ChatGPT | Yes | No custom static header | OAuth | +| Claude web/Desktop custom connector | Yes | No custom static header | OAuth | +| Cursor | Yes | Client support varies | OAuth | +| Codex CLI/app | Yes | Yes | Bearer token or OAuth | +| Claude Code | Yes | Yes | Bearer header with environment variable | +| VS Code / GitHub Copilot | Yes | Yes | Bearer header with secure input | +| Gemini CLI | Yes | Yes | Bearer header with environment variable | +| Windsurf | Yes | Yes | Bearer header with environment variable | +| Zed | Remote MCP | Yes | Bearer header | + +Client menus and availability can vary by version, plan, or organization policy. The linked client documentation is the source of truth for those product-specific requirements. + +## ChatGPT + +ChatGPT custom MCP apps use the OAuth flow: + +1. Open **Settings → Apps**. In a managed workspace, an administrator may need to open **Workspace settings → Apps**. +2. Create a custom app or connector. +3. Enter `PipeOps` as the name and `https://mcp.pipeops.app/mcp` as the MCP endpoint. +4. Select OAuth when authentication options are shown, then connect. +5. On the PipeOps authorization page, paste the dedicated service token and approve the requested access. + +See [ChatGPT developer mode and custom MCP apps](https://help.openai.com/en/articles/12584461) for current availability and controls. + +## Claude web and Claude Desktop + +Claude custom connectors use OAuth: + +1. Open **Settings → Connectors**. +2. Select **Add custom connector**. +3. Enter `PipeOps` and `https://mcp.pipeops.app/mcp`. +4. Select **Connect**, complete the PipeOps authorization page, and approve access. + +Team or Enterprise owners may need to add the connector before members can use it. See [Anthropic's remote MCP connector guide](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp). + +## Cursor + +Add a remote MCP server named `pipeops` with URL `https://mcp.pipeops.app/mcp`, then use Cursor's **Connect** or **Login** action to complete OAuth. See [Cursor's MCP documentation](https://docs.cursor.com/context/model-context-protocol) for the current settings UI and project configuration format. + +## Codex + +For a static service token, store it in an environment variable: ```bash -export PIPEOPS_TOKEN="your-service-token" +export PIPEOPS_TOKEN="sat_your_token_here" ``` Register the hosted server: @@ -64,25 +123,103 @@ Verify the saved configuration: codex mcp get pipeops ``` -Start a new Codex task after adding the server so its PipeOps tools are loaded. You can begin with read-only prompts such as: +Start a new Codex task after adding the server so its PipeOps tools are loaded. See the [Codex CLI repository](https://github.com/openai/codex) for current MCP commands and OAuth support. -```text -What's on my PipeOps account? -List my PipeOps projects and their current deployment status. -Show the environments in my current workspace. +## Claude Code + +Keep the token in `PIPEOPS_TOKEN`, then add this user-scoped remote server: + +```bash +claude mcp add-json --scope user pipeops \ + '{"type":"http","url":"https://mcp.pipeops.app/mcp","headers":{"Authorization":"Bearer ${PIPEOPS_TOKEN}"}}' +``` + +See [Claude Code MCP configuration](https://docs.anthropic.com/en/docs/claude-code/mcp). + +## VS Code and GitHub Copilot + +Add this to your user or workspace `mcp.json`. VS Code prompts for the token and stores it as a password input instead of placing it in source control: + +```json +{ + "inputs": [ + { + "type": "promptString", + "id": "pipeops-token", + "description": "PipeOps service token", + "password": true + } + ], + "servers": { + "pipeops": { + "type": "http", + "url": "https://mcp.pipeops.app/mcp", + "headers": { + "Authorization": "Bearer ${input:pipeops-token}" + } + } + } +} ``` -Before allowing write operations, confirm that the service token includes `api:write`. PipeOps MCP marks mutating and destructive tools so compatible clients can request confirmation. +See [VS Code MCP configuration](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). -## Connect another MCP client +## Gemini CLI + +Add PipeOps to the `mcpServers` object in Gemini CLI settings: + +```json +{ + "mcpServers": { + "pipeops": { + "httpUrl": "https://mcp.pipeops.app/mcp", + "headers": { + "Authorization": "Bearer $PIPEOPS_TOKEN" + } + } + } +} +``` -Use these connection values in any client that supports remote Streamable HTTP MCP servers: +Export `PIPEOPS_TOKEN` before starting Gemini CLI. See [Gemini CLI MCP servers](https://geminicli.com/docs/tools/mcp-server/). -- **Name:** `pipeops` -- **URL:** `https://mcp.pipeops.app/mcp` -- **Authorization header:** `Bearer ` +## Windsurf -Configuration formats differ between MCP clients. Keep the token in the client's secret store or an environment variable when supported. +Add PipeOps to `~/.codeium/windsurf/mcp_config.json`: + +```json +{ + "mcpServers": { + "pipeops": { + "serverUrl": "https://mcp.pipeops.app/mcp", + "headers": { + "Authorization": "Bearer ${env:PIPEOPS_TOKEN}" + } + } + } +} +``` + +See [Windsurf MCP configuration](https://docs.windsurf.com/windsurf/cascade/mcp). + +## Zed + +Add PipeOps to your Zed settings: + +```json +{ + "context_servers": { + "pipeops": { + "url": "https://mcp.pipeops.app/mcp", + "headers": { + "Authorization": "Bearer sat_your_token_here" + } + } + } +} +``` + +Zed's public configuration currently documents literal header values. This places the token in your user settings, so protect the file and do not use a project-shared configuration. See [Zed MCP servers](https://zed.dev/docs/ai/mcp). ## Discover setup from the PipeOps CLI @@ -112,7 +249,13 @@ Tool availability depends on the token scopes and the resources available in its - External and public container registry discovery - Billing plan, subscription, invoice, and card operations -Start with list and get operations before enabling write access for an assistant. +Start with these read-only prompts: + +```text +What's on my PipeOps account? +List my PipeOps projects and their current deployment status. +Show the environments in my current workspace. +``` ### Service-token restrictions @@ -124,16 +267,28 @@ Some sensitive operations remain unavailable even when a token has `api:write` o These restrictions apply to the authenticated request even when the MCP server exposes a similarly named tool. +## Security recommendations + +- Start with `api:read` and enable write access only for a specific task. +- Review tool calls before approving deploy, restart, stop, create, update, delete, billing, or invitation operations. +- Use a separate token per AI client so you can revoke one integration without affecting others. +- Never paste a service token into the assistant's chat. Enter it only in the PipeOps authorization page or the client's protected secret input. +- Revoke tokens you no longer use and rotate any token that may have been exposed. + ## Troubleshooting +### OAuth does not open + +Confirm the endpoint is exactly `https://mcp.pipeops.app/mcp`. Remove and re-add the connection so the client repeats protected-resource and authorization-server discovery. Your client must support remote Streamable HTTP MCP and OAuth. + ### The server is unauthorized -Check that `PIPEOPS_TOKEN` is exported in the environment that starts your MCP client, then restart the client. Confirm that the token has not expired or been revoked. +For OAuth, reconnect or sign in again. For Bearer-token setup, check that `PIPEOPS_TOKEN` is exported in the environment that starts your MCP client, then restart the client. Confirm that the service token has not expired or been revoked. ### A tool is unavailable or forbidden -The service token may be missing a required scope, or the operation may be intentionally unavailable to service-token authentication. Use `api:read` for supported read operations and `api:write` for supported changes. The token is also restricted to its workspace. See [Service-token restrictions](#service-token-restrictions). +An OAuth connection with only `api:read` intentionally hides mutating tools. The underlying service token may also be missing a required scope, the operation may be intentionally unavailable to service-token authentication, or the resource may belong to a different workspace. ### Revoke access -Open [Integrations → Service Tokens](https://console.pipeops.io/dashboard/integrations?cloudIntegrations=tokens) and revoke the token. Remove `PIPEOPS_TOKEN` from the client environment as well. +Disconnect the MCP integration in your AI client to remove its stored OAuth credentials. To guarantee that all server-side access stops immediately, also open [Integrations → Service Tokens](https://console.pipeops.io/dashboard/integrations?cloudIntegrations=tokens) and revoke the underlying token. Remove `PIPEOPS_TOKEN` from client environments and settings if you used static Bearer authentication.