esolved merge conflicts

Author: danciaclara

api-reference/byoa/build-plane-app.mdx

@@ -1,6 +1,5 @@
 ---
 title: Webhooks
-sidebarTitle: Introduction
 description: A webhook triggers a HTTP POST request on the specified url, whenever there is a change in an event. Like a new project is created, updated or deleted then a webhook can be triggered to receive the required payload.
 ---
 ## Creating a webhook

dev-tools/build-plane-app.mdx

@@ -0,0 +1,177 @@
+---
+title: MCP server
+description: Use the Plane MCP server to integrate with Plane
+---
+
+The [Model Context Protocol](https://modelcontextprotocol.io/overview) (MCP) is a
+standardized interface that enables AI models to communicate with external tools and
+services. When combined with Server-Sent Events (SSE), it provides a powerful
+mechanism for real-time data transfer between AI models and external systems.
+
+<Note> 
+Beta
+The Plane MCP Server is currently in **Beta**. Some aspects of the API may change.
+While MCP is standardized, it is also rapidly evolving. The Plane MCP Server aims to
+provide a stable implementation for developers to build robust AI-powered
+applications. Please send any issues to [email protected].
+</Note>
+
+## Prerequisites
+
+Before setting up the Plane MCP Server, ensure you have the following installed:
+
+### Node.js and npm
+- **Node.js**: Version 20 or later (LTS recommended)
+- **npm**: Comes bundled with Node.js
+- **npx**: Comes bundled with npm
+
+You can verify your installation by running:
+```bash
+node --version
+npm --version
+npx --version
+```
+
+If you don't have Node.js installed, download it from [nodejs.org](https://nodejs.org/).
+
+<Note>
+The MCP server uses `npx` to run the `mcp-remote` package, which handles the connection to Plane's MCP server. This is why Node.js and npx are required.
+</Note>
+
+## Using the Plane MCP Server
+
+Follow these steps to integrate with the Plane MCP Server.
+
+### Claude.ai
+
+- Open **Settings** from the sidebar on the web or desktop app.
+- Scroll to the **Integrations** section and click **Add more**.
+- Enter the Integration URL: `https://mcp.plane.so/sse`
+- Click **Connect** to link your Plane workspace.
+
+### Claude Desktop
+
+Add Plane to [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) by
+updating your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "plane": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.plane.so/sse"]
+    }
+  }
+}
+```
+
+### VSCode
+
+Connect Plane to [VSCode](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server)
+by editing your `.vscode.json` or `mcp.json` file:
+
+```json
+{
+  "servers": {
+    "plane": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.plane.so/sse"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+1. Press `Ctrl/Cmd + ,` to open Windsurf settings
+2. Navigate to **Cascade** > **MCP servers**
+3. Select **Add Server** > **Add custom server**
+4. Add the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "plane": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.plane.so/sse"]
+    }
+  }
+}
+```
+
+### Zed
+
+1. Press `Cmd + ,` to open Zed settings
+2. Add the following configuration:
+
+```json
+{
+  "context_servers": {
+    "plane": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.plane.so/sse"],
+      "env": {}
+    }
+  }
+}
+```
+
+## Activating the Plane MCP Server
+
+After setup, when activating the server, you will be prompted in your browser to
+connect your Plane workspace to the MCP server.
+
+When prompted to authorize, click **Approve**.
+
+Next, choose the workspace you want to connect, review the permissions, and click
+**Accept**.
+
+## Troubleshooting
+
+### Common Issues
+
+**Authentication Errors**
+
+If you encounter authentication issues, clear saved auth tokens:
+
+```bash
+rm -rf ~/.mcp-auth
+```
+
+**Connection Timeouts**
+
+- Ensure you have a stable internet connection
+- Check if your firewall or proxy is blocking MCP connections
+- Try using the HTTP endpoint instead of SSE if available
+
+**WSL on Windows**
+
+If you're using WSL on Windows and encountering errors, use this configuration:
+
+```json
+{
+  "mcpServers": {
+    "plane": {
+      "command": "wsl",
+      "args": ["npx", "-y", "mcp-remote", "https://mcp.plane.so/sse", "--transport sse-only"]
+    }
+  }
+}
+```
+
+**Node.js Version**
+
+Ensure you have a recent version of Node.js installed. MCP servers require Node.js 18 or later.
+
+### Getting Help
+
+If you continue to experience issues:
+
+1. Verify your authentication credentials
+2. Contact support at [email protected] for Plane-specific issues
+3. Check the [MCP community forums](https://modelcontextprotocol.io) for general MCP issues
+
+## Congrats!
+
+You have successfully connected your Plane workspace to the MCP server!

webhooks/intro-webhooks.mdx dev-tools/intro-webhooks.mdxwebhooks/intro-webhooks.mdx renamed to dev-tools/intro-webhooks.mdx

@@ -47,12 +47,12 @@
       "url": "self-hosting"
     },
     {
-      "name": "APIs and BYOA",
+      "name": "API Reference",
       "url": "api-reference"
     },
     {
-      "name": "Webhooks",
-      "url": "webhooks"
+      "name": "Dev Tools",
+      "url": "dev-tools"
     }
   ],
   "navigation": [
@@ -74,6 +74,14 @@
         "self-hosting/methods/kubernetes",
         "self-hosting/methods/coolify",
         "self-hosting/methods/portainer",
+        {
+          "group": "Airgapped Edition",
+          "pages": [
+              "self-hosting/methods/airgapped-edition",
+              "self-hosting/methods/airgapped-edition-kubernetes"
+            ]
+        },
+        
         "self-hosting/methods/podman-quadlets"
       ]
     },
@@ -138,13 +146,6 @@
         "self-hosting/troubleshoot/storage-errors"
       ]
     },
-
-     {
-      "group": "App Development",
-      "pages": [
-        "api-reference/byoa/build-plane-app"
-      ]
-    },
     {
       "group": "API Reference",
       "pages": [
@@ -348,8 +349,12 @@
       ]
     },
     {
-      "group": "Webhooks",
-      "pages": ["webhooks/intro-webhooks"]
+      "group": "Build and extend Plane",
+      "pages": [
+      "dev-tools/build-plane-app",
+      "dev-tools/intro-webhooks",
+      "dev-tools/mcp-server"
+      ]
     }
   ],
   "footerSocials": {
@@ -360,5 +365,15 @@
     "ga4": {
       "measurementId": "G-G578SD4VZD"
     }
-  }
+  },
+  "redirects": [
+    {
+      "source": "/api-reference/byoa/build-plane-app",
+      "destination": "/dev-tools/build-plane-app"
+    },
+    {
+      "source": "/webhooks/intro-webhooks",
+      "destination": "/dev-tools/intro-webhooks"
+    }
+  ]
 }

dev-tools/mcp-server.mdx

@@ -166,7 +166,8 @@ The environment configuration file is located at:
 | **WEB_URL** | The complete base URL for the web application including protocol. Essential for email links and integrations. | `http://${APP_DOMAIN}` |
 | **CORS_ALLOWED_ORIGINS** | Comma-separated list of origins allowed to make cross-origin requests to your API. | `http://${APP_DOMAIN}` |
 | **DEBUG** | Toggles debug mode for verbose logging. Set to `1` to enable, `0` to disable. Not recommended in production as it may expose sensitive information. | `0` |
-| **NGINX_PORT** | Port for HTTP traffic. The primary port your users will connect to. | `80` |
+| **LISTEN_HTTP_PORT** | Port for HTTP traffic. The primary port your users will connect to. | `80` |
+| **LISTEN_HTTPS_PORT** | Port for HTTPS traffic. The primary port your users will connect to. | `443` |
 
 ### Scaling and performance
 

mint.json

@@ -21,6 +21,11 @@ Make sure to update the following environment variables in your plane.env file.
     ```
     This is required so that generated links and redirects work correctly behind the proxy:
 
+3. After editing plane.env, restart your instance so the changes take effect:
+   ```bash
+   sudo prime-cli restart
+   ```
+
 ## Proxy setup
 
 1. Choose the appropriate [configuration template](#configuration-templates) for your reverse proxy.

self-hosting/govern/environment-variables.mdx

@@ -20,9 +20,9 @@ Create a Plane client or application per your IdP's documentation and configure
 
 | **Config**                                                                                                                                                                                              | **Value**                                                                                          |
 |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
-| Entity ID  <br/><br/> Metadata that identifies Plane as an authorized service on your IdP                                                                                                                    | `http(s)://domain.tld/auth/oidc/`                                                                  |
-| ACS URL <br/><br/>Assertion Consumer service that your IdP will redirect to after successful authentication by a user <br/><br/>This is roughly the counterpart of the `Callback URL` in OIDC set-ups.       | `http(s)://domain.tld/auth/oidc/callback/` <br/><br/> Plane supports HTTP-POST bindings.           |
-| SLS URL <br/><br/>Single Logout Service that your IdP will recognize to end a Plane session when a user logs out <br/><br/>This is roughly the counterpart of the `Logout URL` in OIDC set-ups.                | `http(s)://domain.tld/auth/oidc/logout/`                                                           |
+| Entity ID  <br/><br/> Metadata that identifies Plane as an authorized service on your IdP                                                                                                                    | `http(s)://domain.tld/auth/saml/`                                                                  |
+| ACS URL <br/><br/>Assertion Consumer service that your IdP will redirect to after successful authentication by a user <br/><br/>This is roughly the counterpart of the `Callback URL` in SAML set-ups.       | `http(s)://domain.tld/auth/saml/callback/` <br/><br/> Plane supports HTTP-POST bindings.           |
+| SLS URL <br/><br/>Single Logout Service that your IdP will recognize to end a Plane session when a user logs out <br/><br/>This is roughly the counterpart of the `Logout URL` in SAML set-ups.                | `http(s)://domain.tld/auth/saml/logout/`                                                           |
 
 <Tip>
 When setting these values up on the IdP, it’s important to remember Plane does not need to provide a signing certificate like other service providers.

self-hosting/govern/reverse-proxy.mdx

@@ -86,7 +86,7 @@ Follow these steps to restore data from a backup:
 2. Use the command ↓ to download the restore script. It’s easiest to save it in the same directory as `setup.sh`.
 
     ```bash
-    curl -fsSL -o restore.sh https://raw.githubusercontent.com/makeplane/plane/master/deploy/selfhost/restore.sh
+    curl -fsSL -o restore.sh https://raw.githubusercontent.com/makeplane/plane/refs/heads/preview/deployments/cli/community/restore.sh
     chmod +x restore.sh
     ```