Dev astroMCP Troubleshooting

Quick diagnostic checklist

• Node.js version >= 18 (node --version)
• MCP server installed (meridian-mcp --version or npx @astromcp-dev/mcp-server --version)
• Cursor config file exists and is valid JSON
• API key is set and valid
• Backend URL is correct
• Cursor restarted after configuration

Installation issues

Error: command not found

If meridian-mcp is not found:

1. Ensure npm global bin is in PATH
2. Use npx @astromcp-dev/mcp-server
3. Reinstall globally: npm install -g @astromcp-dev/mcp-server

Error: cannot find module @astromcp-dev/mcp-server

1. npm cache clean --force
2. npm install -g @astromcp-dev/mcp-server
3. If unpublished, use npx or clone the repo and build locally

Configuration issues

MCP server not appearing in Cursor

1. Confirm config file location:
   • macOS: ~/.cursor/mcp.json or ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
   • Windows: %APPDATA%\\Cursor\\User\\globalStorage\\mcp.json
   • Linux: ~/.config/cursor/User/globalStorage/mcp.json
2. Validate JSON syntax
3. Restart Cursor completely

Invalid JSON in config file

Common mistakes:

// BAD: trailing comma
{
  "mcpServers": {
    "astromcp-dev": { ... },
  }
}

// GOOD: no trailing comma
{
  "mcpServers": {
    "astromcp-dev": { ... }
  }
}

Authentication issues

Invalid API key

Causes:

• Extra spaces or typos
• Key expired or revoked
• Wrong environment variable name

Correct env key:

{
  "env": {
    "ASTROMCP_API_KEY": "astro_..."
  }
}

Rate limit exceeded

If you hit usage limits:

• Check usage in the dashboard
• Wait for reset window
• Reduce request volume or wait for the usage window to reset

Connection issues

Network error: ECONNREFUSED

If using local backend, ensure it is running:

curl http://localhost:8000/health

For production:

curl https://api.astromcp.io/health

Request issues

Endpoint not allowlisted

Use:

Use dev.list_allowed to see all allowed endpoints

Check method and path spelling, and confirm endpoint is in the allowlist.

Endpoint denied by policy

These are blocked by design:

• /api-keys
• /billing
• /acg, /ccg, /relocation
• /meta

Performance issues

If requests are slow:

• Use preset=simple for faster responses
• Avoid heavy enhanced_options unless required
• For Render cold starts, the first call can take 30-60s

Getting help

When reporting issues, include:

node --version
npm --version
ASTROMCP_DEBUG=1 npx @astromcp-dev/mcp-server
curl -i https://api.astromcp.io/health

If needed, contact support with the diagnostic output.