> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 Windsurf 中使用 Linkly AI

> 将 Linkly AI 本地知识库集成到 Windsurf IDE，让 AI 编程助手能够搜索和阅读你的私有文档

## 前置条件

* 已安装 [Windsurf](https://windsurf.com)
* Linkly AI Desktop 已启动，MCP 服务正在运行

## 配置步骤

<Tabs>
  <Tab title="MCP HTTP（推荐）" icon="globe">
    编辑 MCP 配置文件，在 `mcpServers` 中添加：

    <CodeGroup>
      ```json macOS / Linux theme={null}
      // ~/.codeium/windsurf/mcp_config.json
      {
        "mcpServers": {
          "linkly-ai": {
            "serverUrl": "http://127.0.0.1:60606/mcp"
          }
        }
      }
      ```

      ```json Windows theme={null}
      // %USERPROFILE%\.codeium\windsurf\mcp_config.json
      {
        "mcpServers": {
          "linkly-ai": {
            "serverUrl": "http://127.0.0.1:60606/mcp"
          }
        }
      }
      ```
    </CodeGroup>

    保存后重启 Windsurf。
  </Tab>

  <Tab title="MCP Stdio" icon="terminal">
    需要先[安装 Linkly AI CLI](/docs/zh/use-cli)。

    编辑配置文件，在 `mcpServers` 中添加：

    ```json theme={null}
    {
      "mcpServers": {
        "linkly-ai": {
          "command": "linkly",
          "args": ["mcp"]
        }
      }
    }
    ```

    保存后重启 Windsurf。
  </Tab>

  <Tab title="远程访问" icon="globe">
    需要先完成[远程访问配置](/docs/zh/use-in-remote)，桌面端隧道显示{" "}

    <Badge stroke color="green">
      ● 已连接
    </Badge>

    。

    ```json theme={null}
    {
      "mcpServers": {
        "linkly-ai": {
          "serverUrl": "https://mcp.linkly.ai/mcp",
          "headers": {
            "Authorization": "Bearer ${env:LINKLY_API_KEY}"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  配置文件支持 `${env:VAR_NAME}` 语法，可通过环境变量管理 API Key，避免明文写入配置文件。
</Tip>

## 开始使用

配置完成后，在 Windsurf 的 Cascade 面板中直接提问，Cascade 会自动调用 Linkly AI 的工具。例如：

* "搜索我的文档中关于 API 设计的内容"
* "读一下项目需求文档并总结关键点"

## 常见问题

<AccordionGroup>
  <Accordion title="工具未出现在 Cascade 中">
    确认 Windsurf 已完全重启（不仅是关闭窗口），以及配置文件 JSON 格式正确。可在
    Cascade 设置中查看 MCP 服务器状态。
  </Accordion>

  <Accordion title="工具数量上限">
    Windsurf Cascade 最多支持 100 个工具（汇总所有 MCP
    服务器）。如果工具总数超过上限，部分工具可能不可用。
  </Accordion>
</AccordionGroup>