From 6b257a0cff38f055a1aab564f86ca5fb6e7599b9 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Mon, 10 Nov 2025 08:51:33 +0000 Subject: [PATCH] Add Windsurf support to Port MCP documentation - Updated available-tools.md to include instructions for customizing tools in Windsurf. - Modified troubleshooting.md to reference Windsurf in connection instructions. - Expanded _mcp-installation.md with detailed steps for connecting Windsurf to Port's remote MCP server, including configuration methods and troubleshooting tips. --- .../port-mcp-server/available-tools.md | 12 ++ .../port-mcp-server/troubleshooting.md | 4 +- docs/generalTemplates/_mcp-installation.md | 133 ++++++++++++++++++ 3 files changed, 147 insertions(+), 2 deletions(-) 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).