This post is the pre-connect checklist: run the server alone, inspect tools with MCP Inspector, then paste a host config that uses absolute paths.

If you need a starter project, the free MCP Server Generator builds a TypeScript or Python ZIP from a form, and the mcp-server-template repo has the same layout.

1. Start the server in a terminal

From the project folder:

# TypeScript
npm install
npm run build
node dist/index.js

# Python
pip install -r requirements.txt
python server.py

A healthy stdio server sits quiet. It does not print a banner. It waits for JSON-RPC on stdin. If you see logs on stdout, redirect them to stderr before you connect a host.

2. List tools with MCP Inspector

Install and run the official inspector against your command:

npx @modelcontextprotocol/inspector node /absolute/path/to/dist/index.js

Confirm tools/list returns your tools with the expected names and input schemas. Call one tool with sample arguments. Fix schema typos here, not inside Claude.

3. Connect with absolute paths

Hosts do not inherit your shell PATH or working directory. Prefer absolute paths in args.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "weather-helper": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"]
    }
  }
}

Cursor uses the same mcpServers shape in its MCP settings. After saving, fully quit and reopen the app, then ask it to list the tools from weather-helper.

4. Quick failure table

For the longer walkthrough with Windows path notes, see the on-site guide: How to test an MCP server.

This post covers only the connection part: where the config files live, a config shape that survives the way desktop apps launch processes, Windows paths, and a troubleshooting table. The examples use a weather-helper project with one get_weather tool. You can create the same project with the free MCP Server Generator, or clone the mcp-server-template repo, which has both a TypeScript and a Python version.

How a host starts your server

Claude Desktop and Cursor both read an mcpServers object. Each entry is a command plus args. The host spawns that process and speaks JSON-RPC to it over stdin/stdout (the stdio transport). There's no port and no URL. If the process can't start, or if it prints anything that isn't protocol output to stdout, the connection fails.

Two consequences matter:

1. The process is started by a GUI app, not by your shell. Your PATH from .zshrc or .bashrc usually isn't there, and neither is your activated virtualenv.

2. The working directory is the app's choice, not your project folder. Relative paths like src/index.ts resolve somewhere else.

Where the config files are

Claude Desktop

In the app, Settings → Developer → Edit Config opens the file for you.

Cursor

Both files use the same mcpServers format, so one entry works in either.

The config that works: absolute paths to the interpreter and the entry file

Run pwd inside the project folder and substitute it below. These are the same shapes the generator writes into each project's README.

TypeScript (after npm install). Point command at the project's own tsx, so neither npx nor a global install is involved:

{
  "mcpServers": {
    "weather-helper": {
      "command": "/Users/you/mcp/weather-helper/node_modules/.bin/tsx",
      "args": ["/Users/you/mcp/weather-helper/src/index.ts"]
    }
  }
}

If you prefer compiled JavaScript, run npm run build first, then use "command": "node" with "args": ["/Users/you/mcp/weather-helper/dist/index.js"]. If the host can't find node, use the absolute path that which node prints.

Python (after creating .venv and running pip install -r requirements.txt). Point command at the venv's interpreter:

{
  "mcpServers": {
    "weather-helper": {
      "command": "/Users/you/mcp/weather-helper/.venv/bin/python",
      "args": ["/Users/you/mcp/weather-helper/server.py"]
    }
  }
}

A bare "python" is the most common Python failure. It resolves to whatever interpreter the app finds first, which usually doesn't have the mcp package installed. If you use uv, this also works, and it installs dependencies from pyproject.toml on first run:

{
  "mcpServers": {
    "weather-helper": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/you/mcp/weather-helper", "server.py"]
    }
  }
}

The cwd pitfall

Many examples online look like this:

{ "command": "npm", "args": ["start"], "cwd": "/Users/you/mcp/weather-helper" }

It's tidy, and it works in hosts that honour cwd. Some Claude Desktop builds ignore that field. When that happens, npm start runs in the wrong folder, can't find package.json, and exits immediately. The host reports the server as failed, without much explanation. Absolute paths to the binary and the entry file don't depend on cwd, so they behave the same everywhere.

Windows paths

Same idea, different file names:

• TypeScript: C:\Users\you\mcp\weather-helper\node_modules\.bin\tsx.cmd

• Python: C:\Users\you\mcp\weather-helper\.venv\Scripts\python.exe

Inside JSON strings every backslash must be doubled:

{
  "mcpServers": {
    "weather-helper": {
      "command": "C:\\Users\\you\\mcp\\weather-helper\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\you\\mcp\\weather-helper\\server.py"]
    }
  }
}

Test the server before blaming the host

The MCP Inspector starts your server the same way a host does, then lets you list and call tools in a browser:

# TypeScript project
npx @modelcontextprotocol/inspector npm start

# Python project
npx @modelcontextprotocol/inspector .venv/bin/python server.py

Call get_weather with {"city": "Paris"}. The template's placeholder handler echoes the argument back: [get_weather] city="Paris" in TypeScript, [get_weather] city='Paris' in Python. If that works, the server is fine and any remaining problem is in the host config.

After editing the config

• Claude Desktop: quit the app completely (not just the window) and reopen it. It only reads the file at startup.

• Cursor: open the MCP section of Cursor Settings. It lists each server, whether it started, and its tools. Toggle the server off and on after editing.

Troubleshooting

On macOS, Claude Desktop writes per-server logs to ~/Library/Logs/Claude/mcp*.log. On Windows they're under %APPDATA%\Claude\logs. Your server's stderr ends up there too, which is often the quickest way to see the real error.

Summary

Treat the host as a process launcher with no shell: absolute path to the interpreter, absolute path to the entry file, nothing written to stdout, and a full restart after each edit. Check the server in the Inspector first, and the rest is config.

If you want a project where all of this is already in the README, generate one with your own tools at MCP Server Generator, or start from the template repo on GitHub.