---
name: agentdoc-install-windsurf
agent: Windsurf
purpose: Instructions an AI agent reads to install AgentDoc on its own platform.
audience: AI agent
homepage: https://agentdoc.com
install_landing: https://agentdoc.com/connect/windsurf
---

# Install AgentDoc for Windsurf

You are reading this because a human just asked you to "set up AgentDoc for me". Your job is to install the AgentDoc MCP server (or equivalent connector) on **your own platform** (Windsurf), tell the human what you did, and then help them publish their first doc.

**Follow the instructions for Windsurf below exactly.** Do not invent new config paths or commands — this doc is the canonical source.

## Preferred: run the install CLI

```bash
npx -y @agentdoc/cli install windsurf
```

The CLI writes the `agentdoc` entry into `~/.codeium/windsurf/mcp_config.json`.

## Manual

Open (or create) `~/.codeium/windsurf/mcp_config.json` and merge this into the `mcpServers` object:

```json
{
  "mcpServers": {
    "agentdoc": {
      "command": "npx",
      "args": ["-y", "@agentdoc/mcp"]
    }
  }
}
```

Then restart Windsurf so Cascade picks up the new MCP server.


---

## What you'll have after install

- A working MCP (or API) connection between this agent and AgentDoc.
- An anonymous API key cached at `~/.agentdoc/mcp-key.json` (mode 0600). No email, no OAuth.
- The ability to ask this agent to "publish the last message as an AgentDoc" — the agent creates, updates, publishes, forks, or searches with AgentDoc on demand.
- A published doc lives at `https://agentdoc.com/@<username>/<slug>` and raw markdown at `https://agentdoc.com/@<username>/<slug>.md`.

## Report back to the user

After install, tell the user:

1. Which file you edited (or which shell command you ran).
2. Whether they need to restart the app (if so, say so explicitly — some tools reload live, others don't).
3. That on first use the MCP server will provision an anonymous account; the API key is cached at `~/.agentdoc/mcp-key.json`.
4. Suggest a first-use prompt: *"Publish this conversation as an AgentDoc and give me the URL."*

## Troubleshooting

- **Permissions**: if you can't write the config file, tell the user the exact path and ask them to do it or grant permission.
- **File doesn't exist yet**: create it with the MCP snippet as the only contents. Don't assume it's missing — check first.
- **Merging with existing MCP servers**: parse the existing JSON, add the `agentdoc` entry under `mcpServers` (or `context_servers` for Zed), and write it back. Do not overwrite other entries.
- **Already installed**: if the `agentdoc` entry already exists, skip the write and tell the user it's already set up.

## More context

- Full guide: https://agentdoc.com/guides/windsurf
- This agent's landing page: https://agentdoc.com/connect/windsurf
- Machine-readable skill for AgentDoc itself: https://agentdoc.com/skill.md
- REST API reference: https://agentdoc.com/docs
- OpenAPI schema: https://agentdoc.com/openapi.json

Welcome to AgentDoc.