diff --git a/docs/ai-interfaces/port-mcp-server/available-tools.md b/docs/ai-interfaces/port-mcp-server/available-tools.md
index e682f7ab87..9ac300ba11 100644
--- a/docs/ai-interfaces/port-mcp-server/available-tools.md
+++ b/docs/ai-interfaces/port-mcp-server/available-tools.md
@@ -59,5 +59,17 @@ When creating a custom connector in Claude, you can specify exactly which tools
Refer to the [Claude custom connector documentation](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) for detailed instructions.
+
+
+
+In Windsurf, you can customize which tools are available through the UI after connecting to Port MCP. Once connected, you can select specific tools through Windsurf's MCP settings interface.
+
+To manage tools in Windsurf:
+1. Go to **Settings** > **Tools** > **Windsurf Settings**
+2. Find your Port MCP server configuration
+3. Select or deselect specific tools as needed
+
+If you need to limit tools programmatically, you can edit the `mcp_config.json` file directly, though the UI method is recommended for easier management.
+
diff --git a/docs/ai-interfaces/port-mcp-server/troubleshooting.md b/docs/ai-interfaces/port-mcp-server/troubleshooting.md
index f21fc4ae63..c6938026c9 100644
--- a/docs/ai-interfaces/port-mcp-server/troubleshooting.md
+++ b/docs/ai-interfaces/port-mcp-server/troubleshooting.md
@@ -10,7 +10,7 @@ If you encounter issues while setting up or using the Port MCP Server, expand th
How can I connect to the MCP? (Click to expand)
-Refer back to the [setup instructions](./overview-and-installation#installing-port-mcp) for your specific application (Cursor, VSCode, or Claude). Make sure you're using the correct regional URL for your Port organization.
+Refer back to the [setup instructions](./overview-and-installation#installing-port-mcp) for your specific application (Cursor, VSCode, Windsurf, or Claude). Make sure you're using the correct regional URL for your Port organization.
@@ -38,7 +38,7 @@ This is completely normal behavior and doesn't indicate a problem with Port MCP
:::tip Getting Help
If you continue to experience issues, please reach out to Port support with:
-- Your IDE/application version
+- Your IDE/application version (e.g., Windsurf version, Cursor version)
- The specific error messages you're seeing
- Your Port region (EU/US)
- Steps you've already tried
diff --git a/docs/generalTemplates/_mcp-installation.md b/docs/generalTemplates/_mcp-installation.md
index 498247b44f..e0582626ea 100644
--- a/docs/generalTemplates/_mcp-installation.md
+++ b/docs/generalTemplates/_mcp-installation.md
@@ -166,6 +166,139 @@ Failed to validate tool mcp_port_create_action: Error: tool parameters array typ
+
+
+To connect Windsurf to Port's remote MCP server, follow these steps:
+
+:::tip Prerequisites
+Windsurf supports remote MCP servers via HTTP transport. Ensure you have Node.js installed if using the command-based configuration method (Method 2).
+:::
+
+**Step 1: Locate Windsurf MCP Configuration File**
+
+The MCP configuration file is typically located at:
+- **macOS/Linux**: `~/.codeium/windsurf/mcp_config.json`
+- **Windows**: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
+
+If the file doesn't exist, create it with an empty JSON object: `{}`
+
+**Step 2: Configure Port MCP Server**
+
+You can use one of two methods to connect to Port's remote MCP server:
+
+**Method 1: URL-based Configuration (Recommended)**
+
+Add the Port MCP server configuration using the appropriate URL for your region:
+
+
+
+
+```json showLineNumbers
+{
+ "mcpServers": {
+ "port-windsurf-eu": {
+ "url": "https://mcp.port.io/v1"
+ }
+ }
+}
+```
+
+
+
+
+```json showLineNumbers
+{
+ "mcpServers": {
+ "port-windsurf-us": {
+ "url": "https://mcp.us.port.io/v1"
+ }
+ }
+}
+```
+
+
+
+
+**Method 2: Command-based Configuration (Alternative)**
+
+If URL-based configuration doesn't work, you can use the `mcp-remote` package similar to VSCode:
+
+
+
+
+```json showLineNumbers
+{
+ "mcpServers": {
+ "port-windsurf-eu": {
+ "command": "npx",
+ "args": [
+ "-y",
+ "mcp-remote",
+ "https://mcp.port.io/v1"
+ ]
+ }
+ }
+}
+```
+
+
+
+
+```json showLineNumbers
+{
+ "mcpServers": {
+ "port-windsurf-us": {
+ "command": "npx",
+ "args": [
+ "-y",
+ "mcp-remote",
+ "https://mcp.us.port.io/v1"
+ ]
+ }
+ }
+}
+```
+
+
+
+
+**Step 3: Restart Windsurf**
+
+After saving the configuration file:
+1. Completely quit Windsurf (don't just close the window)
+2. Wait 5 seconds
+3. Reopen Windsurf
+4. Wait 20 seconds for initialization
+
+**Step 4: Authenticate with Port**
+
+When you first use Port tools in Windsurf, you'll be prompted to authenticate:
+1. Click on the authentication prompt or "Needs login" indicator
+2. Complete the OAuth flow in the browser window that opens
+3. After successful authentication, Port tools should be available
+
+**Step 5: Verify Connection**
+
+1. Start a new chat session in Windsurf
+2. Look for Port MCP tools in the available tools list
+3. Try asking a question like "List all blueprints in Port" to verify the connection
+
+:::warning Configuration File Location
+If you can't find the `mcp_config.json` file, check Windsurf's settings:
+- Go to **Settings** > **Tools** > **Windsurf Settings**
+- Look for MCP server configuration options
+- You may need to use "View Raw Config" to edit the configuration file directly
+:::
+
+:::tip Troubleshooting
+If the connection doesn't work:
+- Ensure the JSON syntax is correct (no missing commas, proper quotes)
+- Try Method 2 if Method 1 doesn't work
+- Check Windsurf's logs for error messages
+- Verify your Port region (EU/US) matches the URL you're using
+- See the [troubleshooting guide](/ai-interfaces/port-mcp-server/troubleshooting) for more help
+:::
+
To connect Claude to Port's remote MCP, you need to create a custom connector. This process does not require a client ID. For detailed instructions, refer to the [official Anthropic documentation on custom connectors](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).