MCP Server Not Working? Fix Common Setup Errors Fast
MCP server setup fails for four reasons in 90% of cases: wrong config file path, Node.js version below 22, bad or missing license key, or port conflict with another process. This guide walks through each one with the exact command to check and fix it.
MCP (Model Context Protocol) servers run as local processes that AI tools connect to over a standard protocol. When they do not work, the AI tool silently falls back to uncompressed output — or fails to start tools entirely. There is no error shown in the UI. You have to debug the server process directly.
Step 1: Check if the server process is running
Run token-limits status in your terminal. If the server is running you will see a process ID and port. If it is not running, start it with token-limits start. If it fails to start, check the logs with token-limits logs to see the actual error.
Step 2: Check your Node.js version
Token Limits MCP requires Node.js 22 or later. Run node --version. If you see v18, v20, or anything below 22, update Node. The easiest way is through nvm: nvm install 22 && nvm use 22. Then restart the MCP server.
Step 3: Verify your config file path
| Tool | Config file path | How it is set |
|---|---|---|
| Cursor | ~/.cursor/mcp.json | Auto by token-limits setup-cursor |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | Auto by token-limits setup-windsurf |
| VS Code | .vscode/mcp.json (workspace) | Written by token-limits setup-vscode |
| JetBrains Junie | ~/.junie/mcp/mcp.json | Auto by token-limits setup-jetbrains |
| Claude Desktop | Extensions panel (mcpb file) | Drag token-limits.mcpb into extensions |
| Codex CLI | ~/.codex/config.toml | Auto by token-limits setup-codex |
Step 4: Check your license key
An invalid or missing license key causes the MCP server to start but reject all requests. Run token-limits config to see your current key. If it is blank or you see authentication errors in the logs, re-enter your key with token-limits config --key YOUR_KEY. Get your key from your account at tokenlimits.app/account.
Step 5: Check for port conflicts
Token Limits MCP runs on a default port. If another process is using that port, the server fails to start. Check the logs for "address already in use" errors. You can change the port with token-limits config --port 4801 and update your MCP config files to use the new port.
Step 6: Re-run setup for your tool
If the above steps do not resolve it, re-run the setup command for your tool (token-limits setup-cursor, setup-windsurf, setup-vscode, setup-jetbrains). This rewrites the config file from scratch with your current installation settings. Then restart your IDE.
MCP server not showing tools in the UI
If the server is running but tools do not appear in your AI tool's MCP tool list, restart your IDE completely (not just reload window). Cursor, Windsurf, and VS Code cache MCP server lists on startup. A full restart forces them to re-read the config and reconnect.
Get Token Limits MCP working in minutes
Step-by-step setup guides for Cursor, Windsurf, VS Code, JetBrains, and more. Free trial, 50 requests, no credit card.
FAQ
Why is my MCP server not showing up in Cursor?
Most likely causes: the server is not running (run token-limits start), the config path is wrong (re-run token-limits setup-cursor), or Cursor needs a full restart. Check all three in that order.
Why is my MCP server not showing up in Windsurf?
Windsurf reads ~/.codeium/windsurf/mcp_config.json on startup. Run token-limits setup-windsurf to write this file correctly, then fully restart Windsurf (not just reload).
MCP server starts but tools return errors — why?
Usually a license key issue. Run token-limits config to check your key, then token-limits logs to see the actual error. Re-enter your key with token-limits config --key YOUR_KEY.
Does the MCP server need to be running before I open my IDE?
It should start automatically when your IDE reads the config. If it does not, run token-limits start manually before opening your IDE, or set up token-limits to run on login via your system's startup configuration.
Token Limits MCP worked before and stopped — what changed?
Likely causes: Node.js was updated and the version changed, the config file was overwritten by an IDE update, or a new process is using the same port. Re-run the setup command for your tool and check node --version.