Grounded Docs MCP Server for Windsurf: Setup & Config

What you can do with Grounded Docs in Windsurf

Choose it for a version-aware documentation index shared by scripts, a Web UI, and MCP assistants.

• Build a searchable index from local documents and repositories.
• Index hash-routed documentation sites with explicit route preservation.

Before you start: Grounded Docs in Windsurf

• Node.js 22 or later
• An MCP-compatible client for MCP access

The README starts this long-running server, opens its Web UI at http://localhost:6280, and connects MCP clients to the local SSE URL. OPENAI_API_KEY is optional for OpenAI embeddings. CLI and Docker HTTP alternatives are documented.

Grounded Docs Windsurf configuration

1. Choose Windsurf configuration scope

   For Grounded Docs MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Grounded Docs MCP Server to Windsurf

   Use the docs-mcp-server entry below in mcpServers. Keep Grounded Docs MCP Server's documented sse connection fields and your other Windsurf entries.

3. Check Grounded Docs MCP Server in Windsurf

   Grounded Docs MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "docs-mcp-server": {
      "serverUrl": "http://localhost:6280/sse"
    }
  }
}

Grounded Docs tools available to Windsurf

Grounded Docs's stored tool list documents 1 tool; compare it with Windsurf's connected tool list, because the stored list is not a live check.

scrape_docs

After refreshing Grounded Docs in Windsurf settings, check Cascade's tool list for scrape_docs.

Index documentation, with an optional setting to preserve hash-based routes.

Grounded Docs: full stored tool descriptions

Troubleshooting Grounded Docs in Windsurf

• For Grounded Docs MCP Server, Windsurf reads serverUrl (localhost:6280), not url. Refresh the connection and check the tools exposed to Cascade.
• Grounded Docs MCP Server: check sse connectivity to localhost:6280 from Windsurf; a stdio command is not a replacement for this endpoint.
• Transport mismatch: Grounded Docs's catalog lists stdio; the displayed Windsurf configuration uses sse.
• Known limitation: Hash-routed sites require explicit preservation settings and browser rendering.
• Known limitation: Semantic vector search requires configuring an embedding model.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions