Install link generator for MCP Servers produces invalid config parameter

[tasshi (tasshi / Masaharu Tashiro)]

Describe the Bug

This is a bug in the documentation website, not in the Cursor app itself.

The URL obtained using “Copy web link” from the Generate install link tool is broken and cannot be used to install the MCP server.
NOTE: Only the web link is broken; the deep link works correctly.

MCP Install Links | Cursor Docs

The root cause is described in the Additional information section below.

Steps to Reproduce

Use the official sample JSON shown on the page:

{
  "postgres": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-postgres",
      "postgresql://localhost/mydb"
    ]
  }
}

1. Open the “Generate install link” helper on the Developers page.
2. Provide the above JSON (either as { “postgres”: { … } } or the inner object with name=postgres).
3. Click to generate the install link.
4. Open the generated URL in the browser (Cursor deeplink).

The generated link is:

https://cursor.com/en/install-mcp?name=postgres&config=JTdCJTIyY29tbWFuZCUyMiUzQSUyMm5weCUyMC15JTIwJTQwbW9kZWxjb250ZXh0cHJvdG9jb2wlMkZzZXJ2ZXItcG9zdGdyZXMlMjBwb3N0Z3Jlc3FsJTNBJTJGJTJGbG9jYWxob3N0JTJGbXlkYiUyMiU3RA%3D%3D

Then, the Cursor shows the error:

Invalid server configuration provided: Not valid JSON.

When inspecting what Cursor receives, the decoded JSON looks like:

{
  "postgres": "JTdCJTIyY29tbWFuZCUyMiUzQSUyMm5weCUyMC15JTIwJTQwbW9kZWxjb250ZXh0cHJvdG9jb2wlMkZzZXJ2ZXItcG9zdGdyZXMlMjBwb3N0Z3Jlc3FsJTNBJTJGJTJGbG9jYWxob3N0JTJGbXlkYiUyMiU3RA=="
}

This is incorrect because the postgres value is a base64 string of URL-encoded JSON, not the expected command object.

Expected Behavior

The generated link should produce a valid JSON configuration.

The expected link is:

https://cursor.com/en/install-mcp?name=postgres&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtb2RlbGNvbnRleHRwcm90b2NvbC9zZXJ2ZXItcG9zdGdyZXMiLCJwb3N0Z3Jlc3FsOi8vbG9jYWxob3N0L215ZGIiXX0%3D

Screenshots / Screen Recordings

Operating System

MacOS

Current Cursor Version (Menu → About Cursor → Copy)

Version: 1.4.3 (Universal)
VSCode Version: 1.99.3
Commit: e50823e9ded15fddfd743c7122b4724130c25df0
Date: 2025-08-08T17:34:53.060Z
Electron: 34.5.1
Chromium: 132.0.6834.210
Node.js: 20.19.0
V8: 13.2.152.41-electron.0
OS: Darwin arm64 24.5.0

Additional Information

Root cause:

The tool appears to encode in the wrong order:
• Current: encodeURIComponent(JSON) → base64
• Expected: base64(JSON) → URL-encode base64 when placing in query.

This causes the base64 payload to contain %7B%22…%7D instead of raw JSON text.

I checked the cursor/docs repository, but I couldn’t find the code responsible for generating this link.

Minimal fix suggestion:

/**
 * Convert a UTF-8 string to a Base64-encoded string.
 *
 * - In Node.js, uses Buffer for correct UTF-8 handling.
 * - In browsers, uses btoa(), but first encodes to UTF-8 with encodeURIComponent
 *   because btoa() only works reliably with ASCII characters.
 *
 * @param {string} str - UTF-8 string to encode
 * @returns {string} Base64-encoded string
 */
function toBase64(str) {
  // Node.js environment
  if (typeof Buffer !== "undefined") {
    return Buffer.from(str, "utf8").toString("base64");
  }
  // Browser environment
  return btoa(unescape(encodeURIComponent(str)));
}

function generateInstallUrl(name, configObj) {
  const json = JSON.stringify(configObj);    // JSON
  const b64  = toBase64(json);               // base64(JSON)
  const enc  = encodeURIComponent(b64);      // URL-encode base64
  return `https://cursor.com/en/install-mcp?name=${encodeURIComponent(name)}&config=${enc}`;
}

Does this stop you from using Cursor

No - Cursor works, but with this issue