docs: add guidance for local custom MCP setup

docs/configuration.md

@@ -76,6 +76,81 @@ This opens an interactive wizard showing which keys are configured and which are
 4. Environment variables (`export BRAVE_API_KEY=...`) take precedence over saved keys
 5. Anthropic models don't need Brave/Tavily — they have built-in web search
 
+## MCP Servers
+
+GSD can connect to external MCP servers configured in project files. This is useful for local tools, internal APIs, self-hosted services, or integrations that aren't built in as native GSD extensions.
+
+### Config file locations
+
+GSD reads MCP client configuration from these project-local paths:
+
+- `.mcp.json`
+- `.gsd/mcp.json`
+
+If both files exist, server names are merged and the first definition found wins. Use:
+
+- `.mcp.json` for repo-shared MCP configuration you may want to commit
+- `.gsd/mcp.json` for local-only MCP configuration you do **not** want to share
+
+### Supported transports
+
+| Transport | Config shape | Use when |
+|-----------|--------------|----------|
+| `stdio` | `command` + optional `args`, `env`, `cwd` | Launching a local MCP server process |
+| `http` | `url` | Connecting to an already-running MCP server over HTTP |
+
+### Example: stdio server
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "type": "stdio",
+      "command": "/absolute/path/to/python3",
+      "args": ["/absolute/path/to/server.py"],
+      "env": {
+        "API_URL": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+### Example: HTTP server
+
+```json
+{
+  "mcpServers": {
+    "my-http-server": {
+      "url": "http://localhost:8080/mcp"
+    }
+  }
+}
+```
+
+### Verifying a server
+
+After adding config, verify it from a GSD session:
+
+```text
+mcp_servers
+mcp_discover(server="my-server")
+mcp_call(server="my-server", tool="<tool_name>", args={...})
+```
+
+Recommended verification order:
+
+1. `mcp_servers` — confirms GSD can see the config file and parse the server entry
+2. `mcp_discover` — confirms the server process starts and responds to `tools/list`
+3. `mcp_call` — confirms at least one real tool invocation works
+
+### Notes
+
+- Use absolute paths for local executables and scripts when possible.
+- For `stdio` servers, prefer setting required environment variables directly in the MCP config instead of relying on an interactive shell profile.
+- If a server is team-shared and safe to commit, `.mcp.json` is usually the better home.
+- If a server depends on machine-local paths, personal services, or local-only secrets, prefer `.gsd/mcp.json`.
+
 ## All Settings
 
 ### `models`

docs/getting-started.md

@@ -21,6 +21,12 @@ If you use a non-Anthropic model, you'll need a search API key for web search. R
 
 See [Global API Keys](./configuration.md#global-api-keys-gsd-config) for details on supported keys.
 
+### Set up custom MCP servers
+
+If you want GSD to call local or external MCP servers, add project-local config in `.mcp.json` or `.gsd/mcp.json`.
+
+See [Configuration → MCP Servers](./configuration.md#mcp-servers) for examples and verification steps.
+
 ### VS Code Extension
 
 GSD is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "GSD" in VS Code extensions. The extension provides:

docs/troubleshooting.md

@@ -95,6 +95,79 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
 
 **Fix:** GSD auto-resolves conflicts on `.gsd/` runtime files. For content conflicts in code files, the LLM is given an opportunity to resolve them via a fix-merge session. If that fails, manual resolution is needed.
 
+## MCP Client Issues
+
+### `mcp_servers` shows no configured servers
+
+**Symptoms:** `mcp_servers` reports no servers configured.
+
+**Common causes:**
+- No `.mcp.json` or `.gsd/mcp.json` file exists in the current project
+- The config file is malformed JSON
+- The server is configured in a different project directory than the one where you launched GSD
+
+**Fix:**
+- Add the server to `.mcp.json` or `.gsd/mcp.json`
+- Verify the file parses as JSON
+- Re-run `mcp_servers(refresh=true)`
+
+### `mcp_discover` times out
+
+**Symptoms:** `mcp_discover` fails with a timeout.
+
+**Common causes:**
+- The server process starts but never completes the MCP handshake
+- The configured command points to a script that hangs on startup
+- The server is waiting on an unavailable dependency or backend service
+
+**Fix:**
+- Run the configured command directly outside GSD and confirm the server actually starts
+- Check that any backend URLs or required services are reachable
+- For local custom servers, verify the implementation is using an MCP SDK or a correct stdio protocol implementation
+
+### `mcp_discover` reports connection closed
+
+**Symptoms:** `mcp_discover` fails immediately with a connection-closed error.
+
+**Common causes:**
+- Wrong executable path
+- Wrong script path
+- Missing runtime dependency
+- The server crashes before responding
+
+**Fix:**
+- Verify `command` and `args` paths are correct and absolute
+- Run the command manually to catch import/runtime errors
+- Check that the configured interpreter or runtime exists on the machine
+
+### `mcp_call` fails because required arguments are missing
+
+**Symptoms:** A discovered MCP tool exists, but calling it fails validation because required fields are missing.
+
+**Common causes:**
+- The call shape is wrong
+- The target server's tool schema changed
+- You're calling a stale server definition or stale branch build
+
+**Fix:**
+- Re-run `mcp_discover(server="name")` and confirm the exact required argument names
+- Call the tool with `mcp_call(server="name", tool="tool_name", args={...})`
+- If you're developing GSD itself, rebuild after schema changes with `npm run build`
+
+### Local stdio server works manually but not in GSD
+
+**Symptoms:** Running the server command manually seems fine, but GSD can't connect.
+
+**Common causes:**
+- The server depends on shell state that GSD doesn't inherit
+- Relative paths only work from a different working directory
+- Required environment variables exist in your shell but not in the MCP config
+
+**Fix:**
+- Use absolute paths for `command` and script arguments
+- Set required environment variables in the MCP config's `env` block
+- If needed, set `cwd` explicitly in the server definition
+
 ## Recovery Procedures
 
 ### Reset auto mode state