IDE Setup

Learn how to set up the Meldoc CLI as a local MCP server for your IDE. The meldoc mcp init command generates the right config file for each supported editor.

This page covers the CLI-based local server (meldoc mcp serve). For the hosted MCP server at api.meldoc.io, see Getting Started with MCP.

The local server exposes workspace and auth helpers plus the documentation tools proxied from the Meldoc server. Repository operations — scanning, validating, pushing, pulling — are meldoc commands your agent runs in the terminal, not MCP tools.

Claude Code (default)

meldoc mcp init

Creates .mcp.json in your project root with allowedTools for tool permissions:

{
  "mcpServers": {
    "meldoc-cli": {
      "command": "meldoc",
      "args": ["mcp", "serve"]
    }
  },
  "allowedTools": [
    "mcp__meldoc-cli__*"
  ]
}

Cursor

meldoc mcp init --cursor

Creates .cursor/mcp.json:

{
  "mcpServers": {
    "meldoc-cli": {
      "command": "meldoc",
      "args": ["mcp", "serve"]
    }
  }
}

VS Code

meldoc mcp init --vscode

Creates .vscode/mcp.json.

Windsurf

meldoc mcp init --windsurf

Creates .windsurf/mcp.json.

Configuration differences

Target	Path	allowedTools	Use case
Default	.mcp.json	Yes	Claude Code, Claude Agent SDK
Cursor	.cursor/mcp.json	No	Cursor IDE
VS Code	.vscode/mcp.json	No	VS Code extensions
Windsurf	.windsurf/mcp.json	No	Windsurf IDE

allowedTools is specific to Claude Code and the Claude Agent SDK. Other IDEs manage tool permissions differently.

HTTP mode

Prefer connecting straight to the hosted server without a local subprocess? Use --http:

meldoc mcp init --http

Install globally

Add --global to install MCP configuration to your home directory, making it available across all projects:

meldoc mcp init --global
meldoc mcp init --global --cursor
meldoc mcp init --global --vscode
meldoc mcp init --global --windsurf

Global config paths:

IDE	Global config path
Claude Code	~/.claude.json
Cursor	~/.cursor/mcp.json
VS Code	~/Library/Application Support/Code/User/mcp.json (macOS), ~/.config/Code/User/mcp.json (Linux), %APPDATA%/Code/User/mcp.json (Windows)
Windsurf	~/.codeium/windsurf/mcp_config.json

Note: VS Code uses "servers" as the JSON key instead of "mcpServers" in global configuration.

Agent skills

Installs also add Meldoc agent skills. Local installs write them to the project (.claude/skills/, .cursor/skills/, .vscode/skills/, or .windsurf/skills/); global installs use your home directory:

IDE	Global skills path
Claude Code	~/.claude/skills/
Cursor	~/.cursor/skills/
VS Code	~/.copilot/skills/
Windsurf	~/.codeium/windsurf/skills/

Meldoc ships two agent skills:

Skill	What it covers	Download
meldoc-format	frontmatter fields, sibling order, magic links, and the MCP equivalent of each field — for files and for pages written through MCP	https://meldoc.io/skills/meldoc-format/SKILL.md
meldoc-writing	how to write the text: short, one topic per page, link instead of repeating	https://meldoc.io/skills/meldoc-writing/SKILL.md

Each skill is one file, so the URL is a complete install: meldoc skills add <url>, or save it as <skills directory>/<name>/SKILL.md for any tool that reads skills.

Update existing configuration

Use --force to overwrite an existing config:

meldoc mcp init --cursor --force

This re-detects env files and updates the configuration.

Env file auto-detection

If .env or .env.local exists in your project root, meldoc mcp init detects it automatically and adds the --env-file flag:

{
  "mcpServers": {
    "meldoc-cli": {
      "command": "meldoc",
      "args": ["mcp", "serve", "--env-file", ".env"]
    }
  }
}

The CLI server loads MELDOC_TOKEN from the env file for Authentication.

Windows PATH

The installer adds meldoc to your PATH automatically. If your IDE can’t find the binary:

1. Run meldoc setup-path to verify PATH setup.
2. Or use the full path in your config:

   {
     "mcpServers": {
       "meldoc": {
         "command": "C:\\Users\\YourUsername\\AppData\\Local\\Programs\\meldoc\\bin\\meldoc.exe",
         "args": ["mcp", "serve"]
       }
     }
   }

3. Restart your IDE after PATH changes.

What’s next?

MCP Tools Reference — Available MCP tools.

Workspace Management — Switch between workspaces.